Skip to content

Before you start: what we’re building

The ebitex team
Part 1 of 20 of the series “Building Northwind Coffee”: a coffee cup, steaming, beside the part’s number.

Most CMS tutorials teach you where the buttons are. This one is trying to do something harder: explain the shape of a content model well enough that you could design your own, and be able to say why each decision was made rather than only that it was.

So we build one real site, end to end. Northwind Coffee is a speciality roaster — a catalogue of coffees, brew guides, a few shops, a wholesale enquiry form. It is invented; the website is not. It runs against a real organization, and the code for every step of it is public.

What it ends up as

A static site. Vite, React and TypeScript, talking to the Content Delivery API from the browser. There is no server of our own anywhere in it.

That is a real choice rather than a simplification. A content-driven marketing site is mostly cacheable reads, and a static bundle on a CDN is the cheapest, fastest and least breakable way to serve those. The price is that a crawler which does not run JavaScript sees only the shell — worth knowing now, and the subject of a companion series that puts a server in front of this same site.

The part to notice early: the finished app has exactly one route, and it matches everything. What lives at a path is a question only the CMS answers. Publishing a page makes it live — no code change, no redeploy, no ticket. By the end you will have added pages without touching the app at all, which is the whole reason to put a CMS behind a site rather than a folder of markdown.

What you need

An ebitex organization. Not one of ours — there is no shared demo organization, deliberately. A shared one would be read-only in practice, and this series is worth almost nothing if you cannot change a Contract, add a field, break something and get it back. Create one and Content is there.

A Pro allowance. A new organization gets a 14-day Pro trial, which is the window this series is written for and comfortably enough for all of it. Only one step later on genuinely needs Pro afterwards, and it says so plainly when we get there.

Node 20 or newer, and an editor. Nothing else. No database, no container, no local CMS to install.

If you take one idea from this series, take this one: a page is not a file, and a path is not a route. Both are answers the CMS gives, and both can change without a deploy.

Two ways to follow along

Every step both authors content and changes code, which gives you a choice at each one.

Type it. Author the content in Content yourself and write the code as the post describes. Slower, and much the better way to learn — you will hit the small refusals that teach you what a rule is for, which is something reading never does.

Import it. At five points in the series there is a checkpoint bundle: a portable export of everything the content model holds at that step. Import one into your own organization, check out the matching tag, and you are there. Use these to skip a part you do not care about, or to recover when something has gone sideways and you would rather not unpick it.

Bundles import with fresh identity, which rewrites every id and every reference between them. What lands in your organization is genuinely yours from that moment, not a copy pointing at someone else’s content.

How the code is tagged

The sample lives in ebitex-io/samples, and every step is a tag:

git clone https://github.com/ebitex-io/samples
cd samples                      # the repository
git checkout northwind-coffee/step-01
cd samples/northwind-coffee     # the sample inside it

At any tag the sample builds, typechecks and runs. It is not always visually finished — a step that adds a Contract before the code that renders it is a legitimate step, and the post will say so when that is where you are.

Each post carries a block like the one below, naming the tag for that step and, at checkpoints, the bundle:

What this series is not

It is not a feature tour. Features appear when Northwind has a problem that needs one, and never before — you will read why a page needs to be translated before you read the word localization. Where a mechanism is more work than it is worth for a site this size, the post says that too.

It is also not a pitch. There are exactly two places where a plan limit gets mentioned, both of them moments the site walks into a ceiling while doing something entirely reasonable. That is more honest than a pricing table, and considerably shorter.

Part one builds a page.