Skip to main content
Every better-router app is a multi-page app on the server and a single-page app in the browser after the first load — unless you opt out per route. There is no 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.
  1. Server renders HTML and embeds loader data in window.__BR_DATA__.
  2. Client hydrates #app.
  3. <Link href="..."> intercepts clicks, fetches JSON with x-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, set ssr = false in the page’s .server.tsx:
src/routes/app.server.tsx
The first document response still includes the shell and __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.tsx to 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.