# Render public HTML
> SSR owns the document and request boundary. Your application owns the pages, router, data and client hydration.
- Package: `@db3.ai/app/ssr`
- Canonical page: [https://db3.ai/docs/ssr](https://db3.ai/docs/ssr)
- Markdown: [https://db3.ai/docs/ssr.md](https://db3.ai/docs/ssr.md)
- Framework source of truth: `packages/app/src/ssr/README.md`
## Set up a small public page
Use the installed framework and tools from Installation, then install `fastify@5`. SSR is an optional module, not an `App` service. This lab renders public HTML without Vue or hydration so the request/document boundary is easy to see.
- [Installation](https://db3.ai/docs/installation.md)
### Install the HTTP adapter
```bash
npm install fastify@5
```
## Copy the server and runner
The server factory does not listen. The runner exercises it through Fastify injection and closes it afterwards.
### Copy the shipped example
```bash
mkdir -p examples
cp -R node_modules/@db3.ai/app/src/ssr/examples/. examples/
```
## Run it
Expect `200` for a page and recovery, `500` for the controlled failure, `404` for the unknown API route, and true isolation, safe-state, literal-markup and private-error flags.
### Run the lab
```bash
npx tsx examples/runPublicPages.ts
```
## Own the routes and template
`fastifySsr()` receives explicit routes, a document template and a renderer. `/api/health` stays an ordinary JSON endpoint; unknown API paths do not receive an HTML success page.
The app marker is required. Head and state markers are optional for deliberately non-hydrating documents. The renderer returns trusted `appHtml` plus optional status, headers, head or state overrides. The framework does not sanitize arbitrary HTML.
### examples/createPublicPageServer.ts
```typescript
import Fastify, { type FastifyInstance } from 'fastify';
import { SSR_APP_MARKER, SSR_HEAD_MARKER, SSR_STATE_MARKER } from '@db3.ai/app/ssr';
import { fastifySsr } from '@db3.ai/app/ssr/fastify';
/**
* Creates a public HTML route with isolated metadata and escaped JSON state.
*
* The literal body is trusted application markup. Request input goes only into
* the escaped head/state serializers, never raw HTML. This non-hydrating lab
* has no Vue dependency; an application may hydrate the same state separately.
* @returns Server owned and closed by the caller, without a listening socket.
*/
export async function createPublicPageServer(): Promise {
const server = Fastify({ logger: false });
const template = `${SSR_HEAD_MARKER}${SSR_APP_MARKER}`;
server.get('/api/health', async () => ({ ok: true }));
await server.register(fastifySsr({
template,
routes: ['/hello', '/broken'],
/** Collects state on the request-owned context and returns trusted markup. */
async render(context) {
const url = new URL(context.request.url, 'https://notes.example.test');
if (url.pathname === '/broken') throw new Error('Controlled private render failure');
const name = (url.searchParams.get('name') || 'Developer').slice(0, 200);
context.state.name = name;
context.head.title = `Hello ${name}`;
await Promise.resolve();
return { appHtml: '
Your app is running
Literal $& stays literal.
', headers: { 'Cache-Control': 'private, no-store' } };
},
}));
return server;
}
```
## Keep state isolated and safe
Each render gets a new context with state, head metadata and a module set. Never share a mutable Vue app, router, store or authentication state between requests. In a Vue integration, create them inside each render.
Hydration state is escaped JSON inside an `application/json` script. Parse its text content; do not evaluate it. Escaping does not make secrets safe to send to a browser. Only serialize data that the current user may receive.
Head attributes are escaped. Inline head scripts and body HTML must come from trusted application code. The lab puts request input only into escaped title/state values and checks that literal replacement-token text is preserved.
### examples/runPublicPages.ts
```typescript
import { pathToFileURL } from 'node:url';
import { createPublicPageServer } from './createPublicPageServer';
/** Extracts this lab's JSON script contents without evaluating executable code. */
export function pageState(html: string): { name: string } {
const match = html.match(/$&';
const escaped = await server.inject(`/hello?name=${encodeURIComponent(unsafe)}`);
const broken = await server.inject('/broken');
const recovered = await server.inject('/hello');
const missingApi = await server.inject('/api/missing');
return { status: ada.statusCode, isolated: pageState(ada.body).name === 'Ada' && pageState(grace.body).name === 'Grace', safeState: pageState(escaped.body).name === unsafe && !escaped.body.includes('