Skip to main content
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

The Quickstart 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.
src/routes/_document.tsx

Required pieces

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:
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:
See shadcn/ui 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. 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

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.