Skip to content

Moving the chrome into the CMS

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

Northwind’s navigation has lived in two arrays since part 3, and we have edited them three times to publish pages that had nothing to do with code.

This part moves them into the CMS. It is a small diff and the most useful one in the series for anyone with an existing site, because a real migration never starts from nothing — it starts from "we already have a header", and the interesting question is what the before turns into.

Not everything published is a page

The first thing to unlearn.

site-header and site-footer are Components. They have no Experience node, they live at no path, and no page’s content references them. They are content that appears on every page and belongs to none.

Which means they are published as their own roots. Publishing walks a dependency closure — the page, what it binds, what that references — and nothing’s closure ever reaches the header, because nothing points at it. Publish a page and the header is not carried along; it has to be published in its own right.

That is worth knowing beyond the header. Anything with no incoming references is invisible to every closure in the system: a standalone component, a fragment used only by application code, a stream’s projection. If you cannot name what would pull it in, it is a root.

Addressed by name, never by id

The front end asks for site-header by external id.

Not by Guid, and this is the difference between a mechanism that survives being copied and one that does not. A Guid would have to be configured — per organization, per environment, in a variable somebody sets and eventually gets wrong. An external id is a name the content model already carries.

The practical test is the one this sample runs: import the seed bundle into your own organization and the header keeps working, even though fresh-identity import rewrote every single id inside it. Nothing to reconfigure, because nothing was configured.

If a piece of application code needs to name one specific Component, name it by external id. A Guid in your source is a Guid somebody has to maintain.

The fetch itself is deliberately unexciting, and the catch is the entire fallback story:

async function resolve<T>(externalId: string): Promise<T | null> {
  if (!content) return null
  try {
    const expanded = await content.resolveReference({ provider: 'core', key: externalId })
    return (expanded as ComponentValue<T>).content ?? null
  } catch {
    return null
  }
}

The hard-coded arrays stay

Here is the part that looks like a failure to finish the job, and is deliberate: the arrays from part 3 are still there, as fallbacks.

If the header Component is unpublished, or its shape drifts, or a delivery request fails, the site renders its built-in navigation instead. Each half falls back independently — a broken footer does not take the header down with it. And a single link whose target has been unpublished is dropped rather than rendered pointing nowhere.

The reasoning is specific to chrome rather than a general timidity about CMS content:

Chrome is the one thing that must never disappear. Without it there is no way to reach the page that would explain what went wrong.

A product page that fails to render is a bad afternoon. A site with no navigation is a site where nobody can get anywhere — including to the status page, the contact form, or whatever else would let a visitor find out what is happening. The fallback costs a dozen lines that were already written and never has to be right, only present.

This does not generalise to everything. Falling back to hard-coded product copy would be worse than showing nothing, because it would be silently wrong rather than visibly reduced. Chrome is a special case, and it earns the exception because its failure removes the reader’s ability to recover.

What the diff actually is

Two Contracts — a nav link, and a group of them — two Components, and a loader that fetches both once per browser session and hands each half to the component that already existed. The renderers barely change: they took an array before and they take an array now.

That is generally what this migration looks like. The hard part is not the code, it is deciding what happens when the content is not there — which is why the fallback is the design and the rest is plumbing.

Where this leaves us

Every piece of Northwind’s content is now content, and adding a navigation item is an edit rather than a deploy.

Next: the end of the foundation arc. A production build, a sitemap, and the one distinction a static site has to get right about its API keys.