SSR / foldkit-ssr

How the handover works

ConcernFoldkit (renderToString + Runtime.hydrate)foldkit-ssr (SSR.render + SSR.hydrate)
Payload in HTMLInput FlagsPlan's Model slice (no Flags)
Where init runsServer, then again in browserServer only
Server-only dataCrosses if init needs itStays on server unless picked in state
View reading unsent stateRebuilt in browser (dev warning)Refused by SSR.render before serving
Extra setupApplication config onlyOne SSR.plan

Ownership across the handover stays cleanly split:

  • Rendering and DOM adoption stay Foldkit's (renderToString and Runtime.hydrate), gated by a buildId check so stale deployments never decode mismatched envelopes.
  • Application state stays in your Model and update.
  • Normalized server data crosses via Remote.resume(Data) from foldkit-remote.
  • Browser-only queues (such as localStorage outboxes) join after boot via prepare.

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):

ts
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:

ts
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:

ts
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):

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:

ts
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.