> ## 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.

# HTML document shell

> When and how to add src/routes/_document.tsx for title, meta, fonts, and global CSS.

better-router does **not** use Vite's `index.html` or `src/main.tsx`. The plugin generates the client entry and renders HTML on the server. You control the outer shell with an optional **`src/routes/_document.tsx`**.

## Default vs custom

| | No `_document.tsx` | Custom `_document.tsx` |
| - | - | - |
| HTML shell | Plugin **DefaultDocument** (meta, `#app`, scripts) | Your `<html>`, `<head>`, `<body>` |
| When to use | Quickstart, internal tools | Product title, OG tags, Tailwind/shadcn, fonts |
| Client entry | Still `virtual:better-router/client` | Same — do not add `main.tsx` |

The [Quickstart](https://better-router.bansal.io/quickstart.md) works without this file. Add it when you need global assets or branding.

## Create the file

Path: **`src/routes/_document.tsx`** only (root of `routes/`). Nested `_document.tsx` files are ignored.

```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 (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>Acme</title>
        {devScripts}
      </head>
      <body>
        <div id="app">{children}</div>
        <script dangerouslySetInnerHTML={{ __html: stateScript }} />
        <script type="module" src={clientSrc} />
      </body>
    </html>
  );
}
```

### Required pieces

| Prop / element | Purpose |
| - | - |
| `<div id="app">{children}</div>` | Page + layouts render here. Client SPA navigations only replace this subtree. |
| `stateScript` | Inline script setting `window.__BR_DATA__` (loader payload). |
| `clientSrc` | Module URL for the generated client runtime (`<script type="module" src={clientSrc} />`). |
| `devScripts` | Vite HMR + React Refresh in dev. Omit only if you accept broken hot reload. |

Removing any of these breaks hydration or dev HMR.

## Global CSS (Tailwind, shadcn, etc.)

Import processed CSS with a **side-effect import** in `_document.tsx`:

```tsx theme={null}
import "../styles/globals.css";
```

The plugin mirrors those imports onto the virtual **client** entry so Vite injects styles in dev and production. Do **not** use `<link href="/src/styles/globals.css">` for Tailwind — Vite serves processed CSS as JS modules.

Static files in `public/` (favicon, `robots.txt`) can use normal links:

```tsx theme={null}
<link rel="icon" href="/favicon.ico" />
```

See [shadcn/ui](https://better-router.bansal.io/shadcn-ui.md) for a full Tailwind v4 + shadcn setup.

## How this relates to SPA

`_document.tsx` runs on **full document** responses (first visit, hard refresh, `<Link reloadDocument>`, some errors). It is **not** re-run on ordinary `<Link>` clicks — the shell stays, and only `#app` updates. See [SPA navigation](https://better-router.bansal.io/spa.md).

Per-route `<title>` is not a first-class API yet. Options:

* Set `document.title` in a page `useEffect`
* Keep one product title in `_document.tsx`
* Use a head manager library inside layouts (advanced)

## Layouts vs document

| File | Renders |
| - | - |
| `_document.tsx` | `<html>`, `<head>`, `<body>`, scripts |
| `_layout.tsx` | Nav, sidebars — **inside** `#app` |

Never put `<html>` or `<body>` in a layout. That produces invalid markup and breaks hydration.

## Errors and 404

`_error.tsx` and `_404.tsx` still use `_document.tsx` (or the default shell). They do **not** wrap in `_layout.tsx` — include any chrome you need on those pages directly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.