src/main.tsx. The plugin emits virtual:better-router/client, which hydrates #app and handles in-app navigation.
First load vs later clicks
The HTML shell is documented in Document (_document). Layouts wrap route content inside
#app.
Default: SSR, then SPA
No configuration required.- Server renders HTML and embeds loader data in
window.__BR_DATA__. - Client hydrates
#app. <Link href="...">intercepts clicks, fetches JSON withx-better-router-navigate: 1, swaps the page.
<Form> from better-router/react uses the same JSON channel for mutations when SPA is enabled.
Details of the payload and hooks: SSR, hydration, and SPA.
Build an SPA-first route
To skip server HTML for a route but still use loaders and client navigation, setssr = false in the page’s .server.tsx:
src/routes/app.server.tsx
__BR_DATA__, but #app may be empty until the client renders. Useful for heavy client-only UI or dashboards behind auth.
Force a full document load
Use full loads when you need a fresh document shell, non-React assets, or island pages.
What not to do
- Do not restore Vite’s
index.html+createRoot(#root)as the app entry. That bypasses SSR, loaders, and the generated router. - Do not expect
_document.tsxto run on every navigation — put shared UI in_layout.tsx, global CSS in_document.tsx(see Document).
Modes at a glance
Island and SSR pages can coexist. Mixing is common: marketing SSR + app dashboard SPA shell.