Part 1 promised that the key moving server-side has a cost, and that it arrives immediately. Here it is: a browser that cannot hold a key cannot query the Delivery API.
The static sample makes four Delivery calls from the browser, and it is right to. Its key is browser-safe and ships in the bundle by design. Move that key behind import 'server-only' and all four stop compiling — which, as costs go, is the good version. The build fails instead of the site quietly failing at runtime.
So: four calls to replace with endpoints of our own. Except it was one.
Three of the four were links, not queries
Looking at what those calls actually did:
| Call | What it was really asking |
|---|---|
| A card's target path | Where does this thing live? |
| An origin card's target path | Where does this thing live? |
| A guide index listing | Where does each of these live? |
| The coffee browser | Which coffees match these filters, and how many of each? |
Only the last one is a query. The other three are links — and a link's address already arrives with the content. Turning on referencePaths (part 2) puts every reference's published path on the value the renderer is already holding, so those three calls had nothing left to ask.
They were also, not coincidentally, the three that rendered nothing server-side. A whole-organization listing fetched in an effect to find one entry by key is a pattern worth retiring on its own merits; the server just makes it impossible to ignore. The fourth one rendered nothing server-side too, and that turned out to be a choice rather than a consequence — which is the next section.
A private key forces you to own a server endpoint for queries, not for links. That is the rule we would have liked at the start, and we arrived at it by building three endpoints we then deleted.
The one endpoint that was real
The coffee browser genuinely is dynamic: a filtered, paged stream query plus two facet counts, re-run whenever the visitor changes a filter. That needs a server endpoint, and the sample has exactly one.
Having been forced to own it, it turns out to be better than what it replaced. The static sample makes three parallel browser requests — a page of results and two facet counts. A server can fan out on the client's behalf, so the endpoint returns all three in one response. And a request that is only paging an existing result skips the facets entirely, because paging cannot change them.
That is worth noticing when weighing the cost. A seam you are forced to own is sometimes a seam worth owning: three round trips became one, and the rule about when to skip work moved to the one place that can see the whole request.
Owning an endpoint does not mean giving up the HTML
There is a trap in that arrangement, and we walked straight into it. Having built the endpoint, the grid fetched from it — on mount, in the browser, the way it always had. Which meant /coffees, the page the whole catalogue hangs off, served a search box, a set of facet counts all reading zero, and not one of the six coffees to anybody who does not run JavaScript. Three thousand bytes of furniture.
That is the trade-off the static model makes, reappearing inside the server-rendered sample on its flagship browse page. We had moved the key, kept the fetch, and quietly lost the thing the server was for.
The fix is not to give the endpoint back. The page resolves the first page of results and both facet counts on the server — it has the key, and it is already awaiting a resolve — and hands them to the grid as its initial state. The grid renders them, and does not fetch anything until the visitor changes a filter. From then on it owns the interaction, exactly as before.
/coffees 3,127 B, none of the six coffees
→ 10,774 B, all six
A shared link carrying filters (/coffees?roast=light) is server-rendered too, so it is crawlable rather than being a shell that only fills in for a human. The browser makes zero requests to our endpoint on arrival, and exactly one on the first filter change.
A client-owned endpoint is about who answers the next question, not the first one. The first answer can always come with the page, because the server is already resolving something.
This is the one gap in this sample we did not find by reasoning about it. We found it by fetching the page and reading the HTML — which is worth doing to your own site, because a status code cannot tell you, and neither can a browser.
The sitemap: one function, two models
The other thing a static build does at build time and a server can do per request is the sitemap.
The static sample generates it in a build script. The server sample serves it from a route handler. Both call the same function from the SDK:
// app/sitemap.xml/route.ts
import { buildSitemapDocuments } from '@ebitex/content-sdk/sitemap'
const result = await content.delivery.getSitemap({ site })
const documents = buildSitemapDocuments(result, {
origin,
shardPath,
// Which pages are really French. Part 5 is about why only this app can say.
localeUrl,
})
// documents[0] is the index when there are shards, and the whole sitemap when there are not.
const shard = shardFromPath(new URL(request.url).pathname)
const document = shard === null ? documents[0] : documents.find((d) => d.path === shardPath(shard))
return new Response(document.xml, {
headers: {
'Content-Type': 'application/xml; charset=utf-8',
'Cache-Control': 'public, max-age=300, stale-while-revalidate=3600',
},
})
When we first built both, we ran them against the same organization with the same origin and diffed the output: byte-for-byte identical, twenty-two URLs each. They are not identical any more, and the reason is the useful part. The server sample now tells its sitemap which of its pages have a real French version — part 5 is about why that is its decision and nobody else’s — so its sitemap also lists the French addresses of the three pages it vouches for, each pair linked by hreflang. The static sample passes no such callback, and lists the same twenty-two pages once each.
One identity cannot drift, because it is structural rather than tested, and it is why the route reaches for buildSitemapDocuments rather than the single-document buildSitemapXml it could have called. A sitemap is capped at fifty thousand URLs and fifty megabytes; past either, this one splits the site across an index plus shards. Below both, it returns exactly one document, built by the same call the single-file function makes — so there is nothing to give up by writing it this way on a site this small, and the day a catalogue outgrows one file is not a day anyone wants to hear about from a crawler.
That matters more than it sounds, because it is a design claim being tested rather than restated. The SDK deliberately ships no sitemap route adapter — no handler, no CLI, no framework integration — on the reasoning that serving is hosting, and hosting is the one thing an SDK cannot supply without encoding assumptions about a stack it does not control. What it ships instead is a pure function, and each consumer owns about thirty lines of plumbing.
The risk in that choice is that one of the two models quietly ends up second-class. Where the two now differ is the evidence that it did not: in one callback a consumer supplies, and nowhere in the SDK. Neither had to wait for an adapter written for the other one's stack.
What the server adds here is freshness, not capability. A build-time sitemap is as old as your last deploy, so a page published since then is missing from it until you rebuild. The route regenerates per request, bounded only by its own cache headers — five minutes here, because a crawler is not in a hurry and a page published today should turn up on the next crawl rather than the one after.
One detail that is easy to miss: the route passes an explicit site id. The Delivery API normally infers the site from the request's hostname, and this request's hostname is the app's, not the site's — the same problem a build script has, solved the same way. It is the one place where the route is not simply "the browser's code, moved".
The shards themselves are the other detail, and getting them served is this app's problem rather than the SDK's. They have to live at the root — a sitemap may only list URLs at or below its own location, so one served from /sitemaps/ could not name /about — and the catch-all page route already claims every root path, leaving nowhere to put a handler for /sitemap-1.xml. A middleware rewrite is the way through. Every wrong turn on the way there returned a 200 with the right content type and the wrong document, which is the failure mode this series keeps running into.
Where that leaves the two models
Four parts in, the difference is smaller than it looked from part 1, and it is concentrated in two places.
A server buys you a key that stays private, HTML in the first response, personalization that decides the first paint rather than correcting it, and freshness bounded by a cache rather than by a deploy. It costs you an instance, declarative config becoming code, one endpoint for whatever the browser was genuinely querying, and the freshness problem in part 3 — which is the real one, because it is silent.
Everything else ports. The renderers are unchanged. The content model is unchanged. The seed bundles are the same files.
Which is the point of having built both. The site you are reading this on is still static, and moving it is not on our roadmap. If you have a static site and none of the four things above are problems you have, you are not behind — you are done.
Part 5 is the rest of what a crawler reads: the half of “real HTML” the first version of this sample got wrong.
