> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylonsync.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SSR Overview
> File-based server-side rendering with React, layouts, per-route chunks, and instant client navigation. Replaces Next.js for Pylon apps.
Pylon ships a native SSR runtime so you can serve dynamic pages without bolting on Next.js. Drop a file under `app/`, get a route. React renders on the server, hydrates on the client, and `` makes navigation instant.
```
my-app/
├── app.ts # manifest entry (entities, routes, etc.)
└── app/
├── layout.tsx # wraps every page below
├── globals.css # Tailwind (optional)
├── page.tsx # GET /
├── hello/
│ └── page.tsx # GET /hello
└── gallery/
└── page.tsx # GET /gallery
```
No `next.config.js`, no separate `apps/web`, no proxy in front. `pylon dev` (or the production binary) serves the API, the SSR pages, the JS bundles, the optimized images, and the WebSocket all on one port.
## File-based routes
`app//page.tsx` becomes `GET /`. Use `[slug]` for dynamic segments and `(group)` for grouping folders that don't show up in the URL.
```
app/blog/[slug]/page.tsx → /blog/:slug
app/(marketing)/about/page.tsx → /about
```
Page components receive:
```tsx theme={null}
interface PageProps {
url: string; // full request path
params: Record; // dynamic segments
searchParams: Record;
headers: Record; // lowercased
cookies: Record;
auth: {
user_id: string | null;
is_admin: boolean;
tenant_id: string | null;
roles: string[];
};
}
export default function BlogPost({ params, auth }: PageProps) {
return
{params.slug} — {auth.user_id ?? "anon"}
;
}
```
`auth` is resolved from the session cookie. Anonymous requests get `user_id: null`. There is no extra "get the session" call from your page — the SSR runtime hands it in.
## Layouts
`app/layout.tsx` wraps every page below it. Nested layouts compose:
```tsx theme={null}
// app/layout.tsx
export default function RootLayout({ children }) {
return (
My App
{children}
);
}
// app/dashboard/layout.tsx — wraps every page under /dashboard
export default function DashboardLayout({ children }) {
return (
{children}
);
}
```
Layouts survive client-side navigation — when the user clicks a `` from `/dashboard/projects` to `/dashboard/settings`, the `DashboardLayout` instance stays mounted and only its `children` swap. Sidebar scroll position, open menus, and form state persist.
## How it works
1. Request arrives → Pylon's router matches the URL against `ssr_routes` (auto-discovered from `app/`).
2. Pylon dispatches `render_route` to the Bun runtime over its NDJSON pipe.
3. The Bun adapter `import()`s the page + layout modules, calls `react-dom/server.renderToReadableStream`, and pipes chunks back to Rust.
4. Rust streams them over HTTP chunked-transfer-encoding, splicing `` and `` into `` from the build manifest as the stream flows past.
5. After React's stream ends, Pylon appends `