> This is the Markdown rendition of https://pyxle.dev/docs/architecture/ssr, served for AI agents and assistants.
> Append `.md` to any pyxle.dev URL to fetch its Markdown; the links below already do.
> Index of every page: https://pyxle.dev/llms.txt · Whole docs in one file: https://pyxle.dev/llms-full.txt
> Search the docs: https://pyxle.dev/api/docs-search?q=YOUR+QUERY (returns matching pages as Markdown links)
# Server-side rendering
Server-side rendering (SSR) is the process of turning a `PageRoute` and
an HTTP request into an HTML response. It's the part of the framework
that runs on every page load — so it has to be fast, robust, and
predictable. It's also the part that touches both Python (the loader)
*and* Node.js (the React renderer), so a fair bit of the complexity
lives in the bridge between the two languages.
This doc walks through the SSR pipeline stage by stage. By the end
you'll know exactly what happens between "Starlette receives a GET" and
"the browser hydrates", including the worker pool protocol, the head
merge algorithm, and the streaming response strategy.
**Files (`pyxle/ssr/`):**
| File | Lines | What it does |
|---|---|---|
| `view.py` | 720 | Orchestrates loader, render, head, document assembly |
| `renderer.py` | 310 | Wraps Node.js component rendering (subprocess or worker pool) |
| `worker_pool.py` | 330 | Persistent SSR workers, NDJSON over stdin/stdout |
| `head_merger.py` | 420 | Merges head elements from 4 sources, deduplicates, sanitizes |
| `template.py` | 455 | HTML document assembly (dev + production modes) |
| `__init__.py` | 50 | Re-exports the public surface |
The interesting code lives in `view.py`, `renderer.py`, and
`head_merger.py`. The rest is supporting infrastructure.
---
## The pipeline at a glance
```
HTTP request
│
▼
1. Page handler (Starlette closure)
│
▼
2. build_page_response() ← view.py
│
├──▶ 3. Run @server loader
│ (import compiled module, call function, await result)
│
├──▶ 4. Resolve HEAD
│ (HEAD variable, layout JSX, page JSX, runtime registrations)
│ → merge_head_elements() in head_merger.py
│
├──▶ 5. Render React component
│ → ComponentRenderer.render() in renderer.py
│ → SsrWorkerPool.render() (or per-request subprocess)
│ → Node.js worker bundles with esbuild + React renderToString
│
├──▶ 6. Build the document shell
│ → build_document_shell() in template.py
│ → prefix + suffix HTML, props serialized as JSON
│
└──▶ 7. Stream response
→ StreamingResponse(prefix → body → suffix)
│
▼
Browser
```
Source: `ssr/view.py:51-202`.
If anything goes wrong at any stage, error handling kicks in:
- A `LoaderError` triggers the nearest `error.pyxl` boundary.
- A `ComponentRenderError` (the React component crashes during SSR)
also tries the error boundary.
- An unexpected exception falls through to `render_error_document()`,
which renders the developer overlay (in dev) or a generic
`Server Error` page (in production).
---
## Stage 1: importing the compiled server module
The page handler closure inside `build_page_router()` knows the
`PageRoute` for the current URL. The first thing it does is import
the **compiled Python module** at `PageRoute.server_module_path`:
```python
spec = importlib.util.spec_from_file_location(
page.module_key, page.server_module_path,
)
module = importlib.util.module_from_spec(spec)
sys.modules[page.module_key] = module
spec.loader.exec_module(module)
```
`module_key` is derived from the page's path relative to `pages/`, and it is
**unique per source file**. That matters because a cached module is reused
without re-checking which file it came from, so two pages sharing a key would
mean one silently serving the other's loader and component. The readable form
strips route syntax — `posts/[id].pyxl` reads as `…pages.posts.id` — and
because stripping is lossy (`[id]` and `id`, `(marketing)` and `marketing`,
`my-page` and `my_page` all reduce to one name), a segment that the stripping
altered also carries a short digest of its original text. Ordinary names are
untouched.
In **dev mode**, the module is likewise imported once and reused across
requests — so its module-level globals persist exactly like production.
A rebuild advances a process-wide *reload generation*; the importer
stamps each module with the generation it was built against and
re-imports from disk once the generation advances:
```python
if getattr(cached, GENERATION_ATTRIBUTE, None) == current_generation():
return cached # reuse between rebuilds — globals persist
```
This is the hot-reload mechanism. When you save a `.pyxl` file:
1. The watcher rebuilds the artifacts and advances the reload generation.
2. The next request sees the module's stamp is stale and re-imports it.
3. Python re-reads the new `.py` from disk, re-running its body (module
globals reset) and its `import` statements (so an edited helper module
is picked up too).
4. The new code runs.
In **production mode** (`pyxle serve`), the reload generation never
advances, so modules are imported once at startup and reused for the life
of the process — the same reuse as dev between rebuilds.
Because the module is reused between rebuilds, module-level mutable state
(a counter, an in-process cache) behaves the same in dev and serve. It is,
however, **per-process** — under `serve --workers N` each worker has its
own copy, and nothing survives a restart or an edit. Use a database or
cache for state that must be shared or durable; see the
[data-loading guide](https://pyxle.dev/docs/core-concepts/data-loading.md#loaders-should-be-stateless).
Source: `ssr/view.py` (`_import_server_module`) and `ssr/module_cache.py`.
---
## Stage 2: running the loader
Once the module is imported, Pyxle finds the function tagged with
`__pyxle_loader__ = True` (set by the `@server` decorator) and calls
it:
```python
loader_fn = getattr(module, page.loader_name)
data = await loader_fn(request)
```
Loaders are *always* async — the parser refuses to compile a sync
`@server def`. They take exactly one positional argument named
`request` (a Starlette `Request` object). They return a JSON-
serializable dict.
A few invariants hold:
- **The loader name comes from the metadata.** Pyxle doesn't `getattr`
for "the function with `@server`" at runtime — it looked up the
name once at compile time and stored it in
`PageRoute.loader_name`. This means runtime startup doesn't have
to walk the module looking for decorated functions.
- **The loader is awaited directly.** Pyxle does not wrap it in
`asyncio.shield`, doesn't add timeouts, doesn't catch exceptions
outside of the documented error types. The loader is your code,
and it runs as your code.
- **The result must be JSON-serializable.** If you return a `set`, a
`datetime`, or a custom class, the next stage (`json.dumps`) will
raise `TypeError`. Pyxle catches that and routes it through the
same error pipeline as any other render failure.
If the loader raises `LoaderError`, Pyxle catches it and looks for the
nearest `error.pyxl` boundary up the directory tree. If found, it
renders the error page with the error context as a prop. If not, it
renders the default error document.
If the loader raises any other exception, Pyxle treats it the same way
but logs it as an unexpected failure and includes the stack trace in
dev mode.
Source: `ssr/view.py:341-485`.
---
## Stage 3: resolving the head
The `` of the HTML response is assembled from up to **four**
sources, in order of increasing priority:
1. **Layout contributions** — collected at registry-build time from
`layout.pyxl` (and `template.pyxl`) ancestors of the current page,
in two channels: the layout's `` JSX blocks and the layout's
own `HEAD` variable. The JSX channel is compile-time source and is
filtered for unevaluated `{expressions}`; the `HEAD` channel is
finished HTML and is never filtered, so a layout's site-wide
JSON-LD or inline `
My Page
← prefix ends here
(body HTML streams in here)
← suffix starts here
```
A few things worth noting:
- **The CSP nonce is generated per request.** It's a 24-byte
URL-safe random token (`secrets.token_urlsafe(24)`), attached to
every `