> ## Documentation Index
> Fetch the complete documentation index at: https://better-router.bansal.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Layouts
> Wrap pages with _layout.tsx, load shared data from _layout.server.tsx, and own the HTML document.
A `_layout.tsx` file wraps every page in that directory and below. Layouts compose: `src/routes/_layout.tsx` wraps `src/routes/users/_layout.tsx` wraps `users/[id].tsx`.
```
src/routes/
_layout.tsx # wraps every page
_document.tsx # optional HTML shell
index.tsx
users/
_layout.tsx # wraps /users/*
[id].tsx
```
```tsx title="src/routes/_layout.tsx" theme={null}
import type { ReactNode } from "react";
import { Link } from "better-router/react";
export default function Layout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
Do not return `` or `` from a layout. That belongs in `_document.tsx`. A layout that emits a second `` produces invalid markup and breaks hydration.
## Layout loaders
Pair a layout with `_layout.server.tsx` to load shared data (current user, workspace, nav counts). The returned object is passed as props to **that** layout only — not to child pages. Pages still need their own loader if they need the same data.
```ts title="src/routes/_layout.server.tsx" theme={null}
import { getEnv } from "better-router";
export async function loader() {
return { appUrl: getEnv().APP_URL };
}
```
```tsx title="src/routes/_layout.tsx" theme={null}
import type { ReactNode } from "react";
import { Link } from "better-router/react";
export default function Layout({
children,
appUrl,
}: {
children: ReactNode;
appUrl?: string;
}) {
return (
{appUrl ?? "better-router"}
Home
{children}
);
}
```
`redirect()` from a layout loader works. A common pattern is: public marketing layout at `src/routes/(marketing)/_layout.tsx`, authenticated layout at `src/routes/(app)/_layout.tsx` that redirects to `/login`.
Layout loaders run **before** the page loader, outside-in.
## Document
`src/routes/_document.tsx` is the HTML shell. It owns ``, ``, and ``. Layouts wrap the page **inside** `#app`. The document wraps the whole response.
The file is optional and **root-only**. Nested `_document.tsx` files are ignored. If you omit it, the plugin uses a default shell that already includes `#app`, the `window.__BR_DATA__` payload script, and the client runtime.
Add a custom document when you need a title, fonts, or CSS on every HTML response — including `_error.tsx` and `_404.tsx`. Client `` navigations do not re-render the document; they only swap `#app`.
```tsx title="src/routes/_document.tsx" theme={null}
import type { ReactNode } from "react";
export default function Document({
children,
stateScript,
clientSrc,
devScripts,
}: {
children: ReactNode;
stateScript: string;
clientSrc: string;
devScripts?: ReactNode;
}) {
return (
Acme
{devScripts}
{children}
);
}
```
| Prop | Role |
| ------------- | ----------------------------------------------------------------------- |
| `children` | Rendered page and layouts. Put this in `
`. |
| `stateScript` | Serialized `window.__BR_DATA__` payload. Keep as an inline `