Running a frontend on its built-in sample data

What it is

The website and the dashboard each carry the answers of a seeded Northstack API, exported from it, so each runs on its own with no back-end: every screen of the dashboard, and the website's contact form and licence checkout, work as they do against the API. It is what a single frontend package runs on out of the box, and a "Sample data" notice at the bottom of every page says so, so nobody mistakes it for a connected back-end.

Turning it on and off

There is no flag. One setting decides, NEXT_PUBLIC_API_BASE_URL, compiled in when the app is built:

# empty or missing: the built-in sample data, no API needed
NEXT_PUBLIC_API_BASE_URL=

# set: your API, with the /api suffix
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api

• Without Docker, yarn install and yarn dev in the app's folder with no .env file run on the sample data. A .env copied from .env.example points at the API on http://localhost:8000/api instead.
• With Docker, build the image with --build-arg NEXT_PUBLIC_API_BASE_URL= for the sample data. Without that argument the image is built for the API on http://localhost:8000/api.
• The Full Stack's docker compose up --build always builds both frontends with the API's address.
• After changing the value, restart yarn dev, or run yarn build again, or build the image again.

• Run the dashboard
• Run the website

The dashboard on sample data

Every answer is delayed a fraction of a second on purpose, so the loading states the dashboard ships with are seen.

The website on sample data

The home page and every content page never call the API, so they look the same either way. The two parts that do call it answer in the browser, and on the server for the first paint, from the sample data:

The Sample data notice

While the sample data answers, a "Sample data" notice sits at the bottom of every page, at the end of the page rather than over it, so scrolled to the end it covers nothing. Dismiss hides it until the next full page load.

The address in the second column is whatever the app was built with. While the dashboard runs on the sample data, its workspace footer also says "Sample data for demonstration."; on its own API it never does.

When a connected API stops answering

With NEXT_PUBLIC_API_BASE_URL set, the sample data also stands in when the API cannot be reached at all: not running, a timeout, or blocked because its CORS_ORIGIN does not list the app. An answer the API gave, even a 404 or a 500, is always shown as it is.

• After a failure the API is asked again at most every 30 seconds, and the app goes back to it as soon as it answers.
• The dashboard shows its notice whenever it stands in.
• The website stands in only in the browser: a page its server renders never shows sample data. Its notice shows in yarn dev, and in a production build only when it was built with NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always (in .env before yarn build, or --build-arg NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always with Docker).
• This covers an API that stopped, not an app with no API: the browser keeps trying the address and logs each refused request in its console. With no API at all, leave the address empty.

• The notice keeps showing
• CORS and the API's address

Switching to your API

Set NEXT_PUBLIC_API_BASE_URL to the API's address with the /api suffix, then restart yarn dev or build again. The API must list the app's address in its CORS_ORIGIN. What was changed on the sample data stays in that browser and is not sent to the API.

cp .env.example .env
yarn dev

Start over

Clear the site's data for the app's address in the browser's settings, or run one of these in the browser's console, and the samples come back as they shipped:

localStorage.removeItem("northstack_mock_db_v1"); location.reload();

localStorage.removeItem("northstack_site_mock_db_v1"); location.reload();

Removing it

Once an app runs on your own API for good, delete the sample data from its code, in the app's folder:

yarn remove:mock

• It deletes src/lib/mock/ and the notice (src/components/SampleDataNotice/) with its messages, removes every block marked mock-api in the code, in .env.example, in the Dockerfile and in the app's own guides, and in the Full Stack the marked passages of the root QUICKSTART.md and README.md, and leaves remove:mock as a one-line note that the sample data is already removed. On the website it also drops the documentation lines tagged {mock}. Each file reads as it would had the sample data never been added.
• yarn remove:mock --dry-run lists the changes without making them, and a second run reports nothing left to do. It works before or after yarn remove:demo.
• The app then needs NEXT_PUBLIC_API_BASE_URL set. Run yarn typecheck and yarn build afterwards.
• It deletes code and cannot be undone without version control, so commit first.

Exporting it again from the API

The sample data is the seeded API's own answers, so after you change the seed, export it again. In back-end, with the API seeded and running:

yarn export:mock

It signs in as each seeded account, reads what the two apps show, and writes the dashboard's and the website's seed files beside it, in ../dashboard/src/lib/mock/db/seed/ and ../website/src/lib/mock/db/seed/. Nothing is written to the database. --api http://host:8000 reads another API. A browser holding an older copy discards it on its next load.

How it is built