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

# SPA navigation

> How client-side routing works without index.html or main.tsx, and how to opt into SSR, SPA-only, or full reloads.

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

```mermaid theme={null}
sequenceDiagram
  participant Browser
  participant Server as Hono SSR
  participant Client as virtual client

  Browser->>Server: GET /about (document)
  Server->>Browser: HTML shell + SSR in #app + __BR_DATA__
  Browser->>Client: Load client.js
  Client->>Browser: Hydrate #app

  Browser->>Server: GET /projects (Link click, JSON)
  Server->>Browser: { props, layoutProps, ... }
  Client->>Browser: Re-render #app only
```

| Phase | What updates |
| - | - |
| First request | `_document.tsx` (or default shell) + SSR markup in `#app` |
| `<Link>` navigation | **Only** `#app` (page + layout components) |
| Document shell | Stays from first response (title/CSS unless you change them in JS) |

The HTML shell is documented in [Document (\_document)](https://better-router.bansal.io/document.md). 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.

```tsx theme={null}
import { Link, useRouter } from "better-router/react";

<Link href="/dashboard">Dashboard</Link>
<Link href="/logout" reloadDocument>Sign out (full reload)</Link>

const router = useRouter();
router.visit("/users");
router.refresh(); // re-run loaders for current URL
```

`<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](https://better-router.bansal.io/rendering.md).

## 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`:

```ts title="src/routes/app.server.tsx" theme={null}
export const ssr = false;

export function loader() {
  return { user: "Ada" };
}
```

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

| Mechanism | Effect |
| - | - |
| `<Link reloadDocument>` | Browser navigation, new HTML document |
| `export const spa = false` in `.server.tsx` | That route always full load on visit |
| `*.island.tsx` | Navigating **to** an island route full-loads (no SPA payload) |
| Normal `<a href>` (not `Link`) | Full 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](https://better-router.bansal.io/document.md)).

## Modes at a glance

| Mode | Opt-in | Behavior |
| - | - | - |
| SSR + SPA | default | Server HTML, hydrate, client navigations |
| SPA shell | `ssr = false` | Client render in `#app` with loader data |
| Island | `*.island.tsx` | Static HTML + selective hydration |
| Full document | `spa = false`, `reloadDocument`, islands | Whole page reload |

Island and SSR pages can coexist. Mixing is common: marketing SSR + app dashboard SPA shell.


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