Server rendering and hydration¶

The optional renderer executes the same Python components in Node/Pyodide and uses React DOM's actual server APIs. It is not a separate Python HTML serializer.

Requirements¶

Node.js 22+, the Python CLI and a local runtime from pyreact-forge vendor or PYREACT_FORGE_PYODIDE are required. Browser-only APIs such as document must be used in an effect/event or otherwise guarded; they are unavailable during SSR.

pyreact-forge vendor
pyreact-forge render --offline --mode string
pyreact-forge render --offline --mode static
pyreact-forge render --offline --mode stream

string and static produce the corresponding server markup. The Node renderer supports a real React streaming render with Suspense. The current Python CLI captures that stream before returning it; for progressive HTTP delivery, pipe the Node server.cjs DIST ENTRY stream URL process through a server integration.

Prerender and hydrate¶

pyreact-forge build --offline --prerender
pyreact-forge serve

The output contains initial HTML and a manifest directing the browser bootstrap to hydrate it. Match initial data, route and component structure on both sides. use_id output is tested for matching server/client IDs.

If you use --url /about, the renderer sees that route while generating HTML. This does not create a whole multi-page application export; generate and serve routes deliberately in your deployment integration.

Current limits¶

The CLI starts a runtime per render. It is a development/prerender tool, not a request-isolated production SSR server. Additional micropip packages and custom JS registrations are explicitly rejected by this SSR CLI. Python RSC/Flight, server-function transport, resume APIs and partial prerender integration are not implemented. See the capability matrix.