Skip to content

Your first page

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

The first step of this series is bigger than the rest, and it has to be. Nothing renders until every part of the loop exists, so splitting it would leave you with a step that cannot run — which is the one thing a tutorial step must never be.

By the end of it Northwind has one page, at /about, served from the CMS. Five things have to exist first, and it is worth being clear about what each one is before touching any of them, because the interesting decisions in a content model are all about which of these five a thing belongs in.

A Contract is what content is

A Contract is a content type: a named set of fields, and nothing else. Northwind’s first one is page:

FieldTypeNotes
TitleShort textMandatory. A page cannot be published without one
SummaryShort textThe standfirst, and the meta description
BodyRich textThe page itself

What is not in that list is the point. There is no font, no column count, no "hero style". A Contract has no opinion whatsoever about how any of it looks, and keeping it that way is what makes the rest of this series possible.

It is a discipline that costs something up front. The moment you are modelling a page whose design you can already picture, there is real pressure to add a background-colour field and be done with it. Resist that once and you get something back later: the same content, presented a second way, with no migration and nothing copied.

One decision made now that pays off much later

title, description and body are all declared localizable in this very first step — while the organization has exactly one language and it makes no visible difference at all.

A localizable field stores an envelope rather than a bare value: one default, plus per-locale overrides. With one locale that envelope is always { default, locales: {} }, which looks like ceremony for nothing. It is not. Much later in this series we add a second language, and no Contract, no Template and no renderer changes — the shape was already right.

Deciding that axis early costs almost nothing. Deciding it late costs a migration. It is the single most useful habit this series can hand you, and it only works if the decision is made here.

A Component is the actual content

A Contract is a type; a Component is an instance of it. The About page’s real words — its title, its summary, its body — are one Component of the page Contract, sitting in the library with a name and an external id.

The separation is worth stating plainly, because it is where a lot of CMS confusion lives: a Component is not a page. It is a piece of content that does not know where, or whether, it appears anywhere. That is what lets one Component be used in two places, and what lets content exist that nobody can reach yet.

A Template is how it is presented

A Template is the other half: it names one or more Contracts it can present, and its external id is the hook your code hangs off.

Northwind’s first Template is also called page, which is a coincidence worth breaking as soon as there are two of anything. A Contract and a Template are different things, and conflating them is the most expensive mistake in this whole area — a Contract you have named after its appearance is a Contract you will be unable to reuse.

An Experience node is where it lives

The Experience tree is the site: a root node per site, and a node per address beneath it. A node has a name and a slug, and its path is the slugs of its ancestors joined together. /about is a node whose slug is about, sitting directly under Northwind’s site root.

A node also has a payload — what should be served there. Here that payload is a Presentation: this Template, presenting that Component. Which is the sentence the whole model has been building towards, and it is worth reading twice:

A page is a Template and a Component, placed at a node.

Change the Component and the page says something else. Change the Template and it looks different. Move the node and it lives somewhere else. Three independent changes, none of which requires the other two.

A renderer is your code, found by convention

On the app side a renderer is an ordinary React component. The SDK finds it by file name: src/presentations/page.tsx renders the Template whose external id is page. There is nothing to register.

const Page: PresentationRenderer<PageContent> = ({ component }) => {
  const { title, description, body } = component.content
  return (
    <article>
      <h1>{title}</h1>
      {description ? <p>{description}</p> : null}
      {body ? <RichText fragments={body} /> : null}
    </article>
  )
}

export default Page

component.content is keyed by the Contract’s field external ids, so that PageContent interface is the Contract restated in TypeScript. Keeping that mirror true by hand is a chore, and for now we are going to do it by hand deliberately — ten steps of feeling the problem is what makes the fix worth having when it arrives.

One route, every page

The whole route table:

<Routes>
  <Route path="*" element={<ContentPage />} />
</Routes>

That is not a simplification for the tutorial — it is the finished app. <Experience path={pathname} /> asks the CMS what lives at the current path and renders whatever Presentation is published there, dispatching to the renderer whose file name matches the Template.

A greenfield site can do this from the very first step, which is what Northwind does. If you are retrofitting an existing site you will have hard-coded routes to retire one at a time instead — publish the CMS version, check it, delete the route. That migration gets a post of its own later, because almost nobody starts greenfield.

Publish it

Nothing is delivered until it is published. Publishing walks the dependency closure — the node, the Component bound to it, the Contract and Template versions that Component pins — and freezes a snapshot of the lot. What a visitor gets is that snapshot, not the live content, which is why editing a draft never changes a page that is already out there.

Publish the node, run the app, and /about renders.

Where this leaves us

One page, one Contract, one Template, one renderer. It is not much of a website yet, and the model has a real weakness we have not addressed: a page is one block of prose, and a front page is not one block of prose.

Next: composing a page out of parts, and the first Contract that gets presented two entirely different ways.