Part 1 said the first paint is real HTML, and that is the body. A crawler reads four more things before it gets there: the title and description, the status code, the language the page says it is in, and every other address the page claims as the same content in another language.
The version of this sample the first four parts were written against got every one of those wrong. In the HTML it served, each page’s <title> was the layout’s static Northwind Coffee. There was no description anywhere. French was a ?lang= parameter, served under lang="en", with no hreflang at all. This part is what fixing them taught us, and its code link points at the sample as it is now.
The title was already in the CMS
The static sample sets its title and description from an effect, once the page has rendered. That is the only place a browser-rendered site can set them, and a crawler that does not run JavaScript never sees the result. Ported to a server unchanged it is no better, for the reason part 2 spent a section on: no effect runs during a server render.
Next’s answer is generateMetadata, which runs before the render tree exists. That is exactly what lets it write a <head> a crawler receives, and it rules out anything that needs the page rendered first — so the title has to be something you can get without rendering.
It is. A Contract can declare which of its own fields is its title, the CMS resolves that at publish and freezes it, and GET /path hands it back beside the content:
// app/[[...path]]/page.tsx
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
const { path } = await params
const result = await content.resolveLocation(requestPath(path), await resolveOptions())
if (result.kind !== 'presentation') return {} // the page component owns the 404 and the 308
const { description, image } = metadataFor(result.presentation)
const title = result.title ?? SITE_NAME
return {
title,
description,
alternates: { canonical: result.path },
openGraph: { title, description, url: result.path, locale: result.locale },
}
}
The real one also catches a failed resolve — the next section is why — and marks a missing page noindex. What matters here is the first line of the return: this app holds no map from a page to its heading, so a new kind of page needs no change in it. result.titleSource says which step answered: content for an authored title, name for the node’s own editor label, which is the floor when nothing in the Contract chain declares one.
Two things about it are easy to trip over. The title is frozen at publish, so declaring a title field changes nothing a reader sees until the affected pages are republished — we declared four, and every one of those pages still reported name; after the republish, twenty-two of twenty-two reported content. And the member is optional, because it can genuinely be absent: against an older API, or on a result built locally rather than fetched. Write result.title ?? fallback.
Everything else in the <head> — the description, the social image, the structured data — comes from the app, from one pure function keyed by Contract, because nothing in the CMS declares those. The asymmetry is real rather than an omission: a Page already has a description field, and what is missing is a declaration saying that is the one to use. Keyed by Contract rather than by Template, because a description is a property of what the content is, not of how it is presented.
The canonical link is result.path — where the CMS says the content lives — never the requested URL. ?roast=light is this app’s own state, and building the canonical from the CMS’s answer excludes it by construction rather than by an allow-list somebody has to keep up to date.
The layout, generateMetadata and the page component all resolve the same path, and it costs one request, not three: the SDK’s request cache collapses them. That holds only because all three build their options from one helper. The personalization context is part of the cache key, so a caller passing a slightly different one is not an error — it is silently another request per page. Count the requests rather than reading the code and agreeing with it.
Metadata must not decide how a failure looks
Running first has a cost we did not see coming. Once generateMetadata resolves the page, it is also the first thing an outage hits, and an error thrown there is outside error.tsx entirely — that boundary catches a render, and this is not one. Measured against a dead API: a bare framework 500 with 96 bytes of body, and the recovery page never reached.
The fix is to let metadata fail quietly. It catches, returns the site name, and the page component makes the same call a moment later, gets the same error, and throws it into the boundary built to explain it. The reader loses a description nobody would have missed, and gets a page that says what happened.
The same thinking decides the status codes. A missing page is a real 404 and a renamed one a real 308, and exactly one place issues them: the page component. generateMetadata sees the same result and deliberately does neither, because two places issuing the same redirect stays correct right up until one of them changes.
A language belongs in the address
The static sample keeps the language in ?lang=, which is right for it: a shared link opens in the language the sender was reading. It stops being right the moment a page has a translated slug. A French address under a query scheme gives that page two live French URLs, which is exactly the duplication hreflang exists to resolve.
So French moved into the path. /fr/cafes is French, /coffees is English, and the default locale carries no prefix, because one page at two addresses is the problem canonical exists to clean up after. /en/about is answered with a redirect to /about.
The first version did that in the app. Middleware read the prefix off every request, a pair of helpers stripped it and put it back, and every same-site link went through a wrapper component — and a link that forgot the wrapper did not break. It silently dropped a French reader back into English, which nothing reports.
Then the CMS learned to do it itself. The site is configured pathPrefix in Content, and the app hands the request path to resolveLocation exactly as it arrived. The server reads the locale off it, and every address the API hands back — the page’s own path, a redirect’s target, a navigation link, a reference’s paths, the sitemap — is already in the site’s URL space. The prefix machinery was deleted. Like the personalization port in part 2, getting this right removed code rather than adding it.
<html lang> comes from the same answer, result.locale. A root layout at app/layout.tsx receives no route params, so it cannot see the address; moved into the catch-all segment it gets them, and resolves the page like everything else does — for free, through the request cache. This one is not decoration. lang is what tells a screen reader which voice to use, and a French page declaring English is wrong in a way no test notices.
One trap, and it is part of why this post links to a newer version of the sample than parts 1 to 3 do. Name the site with a function, not a string:
createContentClient({
apiKey,
site: (sites) => sites.find((s) => s.rootNodeId === process.env.CONTENT_SITE_ID),
referencePaths: true,
})
A string is taken at its word, so the client never calls GET /sites — and that is the only place the server publishes how a site puts a locale into an address. A client that never read it sends locale= beside a /fr/… path, and the server refuses the pair with 400 locale_not_addressable on every page, with nothing in the configuration looking wrong. Part 3’s example passes a string, which is correct for a site whose addresses carry no locale and wrong for this one.
hreflang lives in the sitemap
The obvious place for hreflang is each page’s <head>, and that is where we put it first. It advertised a dead URL.
A resolve answers for the locale it was asked about and nothing else. At /coffees it knows /coffees; it does not know that the French edition is at /fr/cafes. Composing the French address from what it does know gives /fr/coffees — which is not a fallback and not a redirect. It is a 404, because once a page carries a French slug its English one is not an address in French at all.
The CMS does know every locale’s path for every page, in one place: the sitemap. Search engines accept a sitemap and a <link rel="alternate"> element as equal ways to declare alternates, and only one of them has the data, so that is where the claim is made — once.
Even the sitemap cannot say which pages are actually translated, and that is deliberate rather than a gap. A language becomes addressable for the whole site the moment any one page has a slug in it, so the CMS reports a French path for all twenty-two pages, and nineteen of them serve English copy at a French address. That is correct. A page is routinely translated while keeping its slug, so a slug was never a translation signal, and nothing in the CMS records whether something has been translated — so nothing can report it.
Which leaves the one party who knows. The sample keeps a short, hand-maintained list, and the sitemap route asks it:
localeUrl: (path, locale, node) => {
if (locale === DEFAULT_LOCALE) return path
return TRANSLATED_PATHS.has(node.path) ? path : undefined
},
Returning undefined drops that alternate, and a page left with a single alternate declares none, rather than naming itself as its own French edition. The function composes nothing — every path already carries its prefix — so what is left for it is the decision. It keys on node.path, the page’s default address, rather than on path, which for a translated page arrives as /coffees in one call and /fr/cafes in the other.
The language switcher does need the same page in every locale, and asks for it: GET /nodes, anchored on the page’s node id, once per locale. So the addresses are no longer what stops the <head> declaring alternates. The claim is, and one surface making it cannot disagree with a second.
It is also why part 4’s two sitemaps are no longer identical: same function, same membership, and three French pages the server sample vouches for while the static one makes no claim at all. A bigger site would derive that list rather than type it — a category on the page, a field on the Contract — and every one of those is a content decision, which is the point. The question belongs in your model, not in ours.
Read the HTML, not the browser
Every finding in this part was invisible from a browser, which renders everything and shows each of these pages as perfect. The check is to fetch the page and read what came back:
curl -s http://localhost:3000/fr/cafes | grep -oE '<html lang="[a-z]+"|<title>[^<]*</title>'
And when checking whether something is rendered, strip the <script> tags first. Next ships the page’s data inside them, so a plain grep over the whole response finds text a crawler never reads as markup, and reports an empty body as a rendered one. It misled us three times while building this, twice about which component was at fault.
One place where the empty body is genuine rather than a trap: Next client-renders its not-found and error boundaries, so their bodies are empty in the HTML whatever they contain. That is fine. A 404 is marked noindex, so the one page whose body a crawler should not read is the one whose body is not there, and the status code — the part a crawler acts on — is real either way.
That is the rest of what part 1 meant by real HTML: a title the CMS already knew, a status code only one place owns, a language that is part of the address, and one honest list of which pages are really French. The site you are reading this on is still static, for the reasons part 1 gave, and that is the fair way to read this list: each item is something a server makes possible, not something every site needs.
