SSR / foldkit-ssr
How the handover works
| Concern | Foldkit (renderToString + Runtime.hydrate) | foldkit-ssr (SSR.render + SSR.hydrate) |
|---|---|---|
| Payload in HTML | Input Flags | Plan's Model slice (no Flags) |
Where init runs | Server, then again in browser | Server only |
| Server-only data | Crosses if init needs it | Stays on server unless picked in state |
| View reading unsent state | Rebuilt in browser (dev warning) | Refused by SSR.render before serving |
| Extra setup | Application config only | One SSR.plan |
Ownership across the handover stays cleanly split:
- Rendering and DOM adoption stay Foldkit's (
renderToStringandRuntime.hydrate), gated by abuildIdcheck so stale deployments never decode mismatched envelopes. - Application state stays in your
Modelandupdate. - Normalized server data crosses via
Remote.resume(Data)fromfoldkit-remote. - Browser-only queues (such as
localStorageoutboxes) join after boot viaprepare.
Beyond the handover, you can adopt static regions (SSR.static) that skip
browser rendering, resumable pages (Resume.builder) that queue clicks and
typing before boot, and server-handled forms (fallback: 'server') that
work with JavaScript disabled.
The rest of this guide uses a post page application (App, Model, Message,
config), defined in full under
The application in these examples.
Commands init would have run: boot
Because the browser skips init, any startup Commands returned by init must
be listed in boot (otherwise SSR.render refuses the plan with
UndeclaredStartup):
const Post = SSR.plan(App, {
id: 'post',
state: Projection.pick(App.model.route, App.model.draft),
boot: () => [LoadPreferences()],
})Applications using foldkit-bundle run their assembly startup Commands here so
Mirror.kv restores persisted client state:
boot: model => assembly.init(model).commands ?? []Styles in the first paint
Pages styled with foldkit-mixins can inline only the CSS classes used during
the render so the first paint is styled before scripts load:
import { Style } from 'foldkit-mixins'
const html = SSR.page(template, result, {
head: (_rendered, drawn) => `<style>${Style.usedDrawn(drawn)}</style>`,
})Style.usedDrawn(drawn) emits rules and keyframes for the classes rendered in
that pass (also exposed on result.drawn; Style.usedIn(rendered.html) works
when holding raw HTML). In the browser, Styles skip rules already present in
this sheet. With foldkit-mixins/vite, link the hashed CSS asset in head
with <link rel="stylesheet" href="${href}" data-foldkit-styles-href>.
For dynamic serving via SSR.entry (where the host owns index.html), pass
styles so theme and used-class styles append inside the rendered root and
move to <head> when SSR.hydrate runs
(examples/foldkit/ssr/src/renderPage.ts):
const styles = (_rendered: { readonly html: string }, drawn: ReadonlySet<string>): string =>
`<style>${stylesheet}</style><style>${Style.usedDrawn(drawn)}</style>`
SSR.entry(config, Post, { buildId, styles })Keep styles to <style> and stylesheet <link> tags; void root elements
cannot hold child style tags (VoidRootWithStyles). SSR.generate accepts the
same head option as SSR.page and returns 500 if head throws.
The head is part of the view
title, lang, dir, canonical, and ogUrl are verified alongside the
body. Derive canonical from the route in your Model (and include the route
in state) whenever needed. Foldkit populates canonical and og:url into
existing <link rel="canonical" href=""> or <meta property="og:url" content="">
tags in the template and fails the render if the template lacks them.
What a page says of itself: meta
Add meta to a plan to populate description, Open Graph, Twitter cards,
article dates, and JSON-LD tags:
const Post = SSR.plan(App, {
id: 'post',
state: Projection.pick(App.model.route, App.model.post),
meta: model => ({
description: model.post.excerpt,
type: 'article',
article: { published: model.post.publishedAt },
jsonLd: [{ '@context': 'https://schema.org', '@type': 'BlogPosting', headline: model.post.title }],
}),
})SSR.page and SSR.generate inject escaped tags carrying
data-foldkit-meta (META_ATTRIBUTE) before </head> (leave matching tags out
of the base template), and SSR.render checks that meta reads only sent
fields (ViewDependsOnUnsentState). SSR.hydrate updates those tags on
in-app navigation. image accepts an absolute URL (plus imageSize and
imageAlt), and article accepts authors and tags.