The whole of server-side rendering with this SDK is one sentence: resolve where the request is, and pass the result in.
const result = await content.resolveLocation(path)
return <ContentRoot result={result} />
Everything else in this part is a consequence of it. Two of those consequences are obvious once stated. The third rendered every card on Northwind's home page as unlinked text, and we did not notice until we looked at the delivered HTML.
The renderer map cannot cross the boundary
A server component resolves the page and passes result, which is plain JSON. The renderers live on the other side of a 'use client' boundary:
// app/content-root.tsx
'use client'
import { ContentProvider, Experience } from '@ebitex/content-sdk/react'
import { renderers } from '@/lib/renderers'
import { Markdown } from '@/components/Markdown'
export function ContentRoot({ result }) {
return (
<ContentProvider renderers={renderers} markdown={Markdown} fallback={() => null}>
<Experience result={result} />
</ContentProvider>
)
}
It has to be that way round, and the reason is not about this SDK: a renderer map is a map of component functions, and functions are not serializable, so it can never be handed from a server component to a client one. Build it inside the boundary and let only the resolved result cross.
Two smaller things fall out of that, both worth knowing before you hit them:
Everything below that wrapper is in the client graph automatically. The renderers keep using hooks freely and need no directive of their own — the boundary is declared once, where the map is built. But a component the server renders directly does need one. Moving the site chrome server-side, so the header arrives with the document, pushed the boundary down to the two switchers inside it: being imported by a client component is what had been putting them in the client graph, and the chrome had just stopped being one.
'use client' marks a module, not an export. Our lib/locale.ts exported both a LOCALES array and the hooks that use it; once the page resolved the locale server-side it crashed at request time with LOCALES.some is not a function, because the array had become an opaque client reference. Data and hooks belong in separate modules, and the failure is at request time rather than build time, which is what makes it worth saying out loud.
No effect runs during a server render
This is the one that cost us a page.
The static sample links a card to its target by fetching a listing in a useEffect, building a map of keys to published paths, and looking the binding up in it. That is correct in a browser. Ported unchanged to a server it renders every card as a div — a grid of text with nothing to click — because renderToString is synchronous and no effect ever runs.
A crawler sees that. A reader with JavaScript disabled sees that. The page looks perfect the moment it hydrates, which is exactly why nobody notices.
The fix is not to run the effect earlier. The address was already in the document:
createContentClient({ apiKey, site, referencePaths: true })
With referencePaths on, every reference in a delivered document carries its own target's published path, so the renderer reads it off the value it already holds and resolves nothing. Set once at construction rather than per call — the resolved shape is part of the cache key, so a per-call flag would split two callers asking for the same page into two requests.
Worth knowing that this survives an Adapter. Northwind's home-page cards are Adapter-mapped: the renderer is handed a card and is documented as not knowing that coffees exist. Each one still carries its target's real /coffees/… path, because an Adapter changes the shape delivered and never the identity. We measured that rather than assuming it, since it is the case where you would most reasonably expect the address to be lost.
The general rule this leaves: a renderer that resolves anything in an effect has no server-side output at all. Not an error — an absence. Go looking for them in the delivered HTML rather than in the rendered page.
We found the second instance of this by deleting the obsolete helper module and letting the build point at every caller. That is a better search than grepping for the pattern.
Personalization arrives with the request
The static sample holds the visitor type in localStorage behind a useSyncExternalStore, and its own comment explains why the store is needed: the footer switcher and the code resolving the page are two consumers who have to agree.
Server-side there is no second consumer, because the server already resolved the page against the value. So the store, its subscribe/snapshot pair, and the getServerSnapshot the port had to add all disappear. What replaces them is a cookie read in the server component:
const cookieStore = await cookies()
const buyerType = parseBuyerType(cookieStore.get(BUYER_COOKIE)?.value)
const result = await content.resolveLocation(path, { context: { buyerType } })
The port removed code rather than adding it, which is the strongest form this argument takes.
The context bag is passed per call, not configured on the client. context also accepts a zero-argument function, and on one client shared by every request that function has no way to know whose request it is. Per call is one line and cannot get this wrong.
One client serving every visitor reads alarming next to the word personalization, so it is worth saying why it is safe: the context bag is part of every cache key, so two visitors with different bags cannot be served each other's content. That is structural rather than a matter of care. We still drove it — alternating two cookie values against one running process, which returned the right variant every time.
Live preview needs nothing extra
Composer's live preview posts a draft document into your running site and renders it in place. The obvious worry with a server-rendered page is that the document arrives too late: the HTML was built before the draft existed.
It does not, for a site that hydrates. The server render is the first paint and the bridge takes over on hydration, exactly as it does in the static sample. Mount it in the client wrapper and there is nothing else to do — no token, no draft reading on the server, no second code path.
We drove the protocol end to end rather than reasoning about it, and the framed page rendered an unsaved title with its pins drawing over the site's own server-rendered chrome. The flag changes nothing server-side either: a page requested with the preview parameter renders published content byte-identically, because the bridge is inert until it is both framed and flagged.
Part 3 is the one a reader is most likely to get wrong unaided, and the one where our own documentation was wrong.
