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:
<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:
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.titlein a pageuseEffect - 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.