Skip to content

Types you didn’t write

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

Rename a field in the CMS. Northwind’s app keeps compiling.

That is the problem, and it has been true since part 4. src/lib/cmsTypes.ts restates every Contract as a TypeScript interface, by hand, and nothing anywhere connects the two. The Contract is the truth; the interface is a claim about the truth, made once, by a person, in a different repository from the thing it describes.

It has never been wrong in this sample, because the same person changed both within a minute of each other every time. That is not a property you can rely on with two people, or one person and a fortnight.

The Delivery API already knows

The fix is not clever, which is why it works. The Delivery API can describe its own content: every Contract, every field, every modifier, as JSON Schema — the actual delivered shape, not the authored one.

So npm run codegen reads that and writes src/types/content.d.ts. cmsTypes.ts is deleted, and this part is mostly a diff with a lot of red in it.

The generated file is committed. That matters: a contributor can clone, install and build with no credentials at all, and CI does not need a key to typecheck. Regenerating is a deliberate act after a model change, not something a build silently does — which also means the diff shows up in review, where a surprising one is worth a conversation.

The key it reads is the one from last part

Codegen runs in Node and reads CONTENT_DELIVERY_KEY — the server-side key, not the VITE_ one.

Same reason as the sitemap script, for exactly the same mechanical cause: a browser-safe key is restricted by Origin, and Node sends no Origin header. Point codegen at the browser’s key and it is refused with 403 origin_denied, which is at least a legible error rather than a mysterious empty schema.

This is the second script in two parts to need the unrestricted key. That is a pattern worth expecting: build-time tooling is server-side by definition.

It is one script and one command:

"scripts": {
  "codegen": "node scripts/codegen.mjs"
}

And this is what it writes — the Contracts, restated in TypeScript, with the version each was generated from recorded above it:

// Generated by `content-sdk codegen` — do not edit by hand.

/** coffee (601d3ff2-7e0a-4c6a-a789-0191d909eec9@2) */
export type Coffee = {
  name: string
  producer?: string
  description?: RichTextValue
  "tasting-notes"?: Array<string>
  price?: number
  image?: ComponentValue<Image>
  origin?: ComponentValue<Origin>
  roast?: CategoryDescriptor
  process?: CategoryDescriptor
}

Every optional marker there is the Contract’s own: name is mandatory and producer is not, so the compiler makes you handle the difference everywhere you touch one.

The other half of the pair. Every optional marker in the generated type is one of these modifier icons, read off the Contract rather than remembered.

What generated types push back on

Two knock-on changes, both consequences of the generated types owning the Contracts’ own names.

Renderers had to be renamed. const Page: PresentationRenderer<Page> shadows itself the moment Page is a generated type rather than a local interface. The local name is free, so the renderers became GeneralPage, CoffeePage, GuidePage — following the CoffeeIndexPage this project already had.

That is a small piece of pressure in a useful direction. When the type is named after the Contract, the component has to be named after what it does, and having both share a name was always a coincidence rather than a design.

CoffeeIndex.tsx became CoffeeGrid.tsx, which is what it is. It was named after the page it appeared on; it renders a grid.

Generate against your own content, early

The advice this step is really making is not about ebitex specifically, and it is worth taking whatever content API you are integrating with.

Generate types from your own live content, on day one. Not from a fixture, not from an example payload in the documentation — from the organization you are actually going to ship against, with the model you have actually built.

A schema and the response it describes are two different artifacts, and the only thing that keeps them honest is somebody depending on both at once. A fixture cannot do that, because a fixture is written by the same person, on the same day, with the same assumption. Generated types can, because the compiler checks every place your code touches the delivered shape and stops on the first disagreement.

A test asserts what somebody thought to assert. Generated types assert the whole surface, including the parts nobody thought about.

It is also the cheapest possible version of that check: one command, run in CI, that fails the build when the model and the code have drifted apart. Northwind runs it on every content change.

Where this leaves us

One fewer file, and a compiler that now disagrees with you when the model changes.

That is the smallest part in the series and among the most satisfying. Next, back to modelling: Ethiopia is named by three coffees and says the same thing on all three pages, which is both the point of a reference and its limit.