# React Router v8 — framework and data mode

> Verified 2026-09 against https://remix.run/blog/react-router-v8 and https://reactrouter.com. The main non-Next.js path for SSR + data loading in React.

## 1. Version facts (v8, June 2026)

- ESM-only. Minimums: Node 22.22+, React 19.2.7+, Vite 7+.
- `react-router-dom` is removed — import from `react-router` (and `react-router/dom` for `RouterProvider`/`HydratedRouter` DOM entry points).
- Former future flags are now default: middleware, pass-through requests, trailing-slash-aware data requests, Vite Environment API; `splitRouteModules` is a top-level config option.
- Server Components are opt-in and still marked unstable.
- Remix v2 was folded into React Router v7 framework mode; "Remix 3" is a separate, non-React framework. Do not recommend Remix for a React app.

## 2. Modes — pick one

| Mode | What you get | Pick when |
|---|---|---|
| Declarative | `<BrowserRouter>`, `<Link>`, `useNavigate` | Tiny apps, or a data layer with its own pending-state handling (local-first, sync engines) |
| Data | Route objects with `loader`, `action`, `useFetcher`, pending states; you own bundling and server | Vite SPA that wants loaders; existing v6.4+ data routers |
| Framework | Data mode + Vite plugin: typed `href`, typed route modules, automatic code splitting, SPA/SSR/static rendering | Anything new that would otherwise consider Next.js or TanStack Start |

## 3. Route module (framework mode)

```tsx
// app/routes/orders.$id.tsx
import type { Route } from './+types/orders.$id';
import { Form, redirect } from 'react-router';
import { getOrder, updateOrder } from '~/features/orders/api/orders.server';

export async function loader({ params }: Route.LoaderArgs) {
  return { order: await getOrder(params.id) };
}

export async function action({ request, params }: Route.ActionArgs) {
  const data = await request.formData();
  await updateOrder(params.id, { note: String(data.get('note')) });
  return redirect(`/orders/${params.id}`);
}

export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
  return <p role="alert">{error instanceof Error ? error.message : 'Something went wrong'}</p>;
}

export default function OrderRoute({ loaderData }: Route.ComponentProps) {
  return (
    <Form method="post">
      <h1>{loaderData.order.number}</h1>
      <input name="note" defaultValue={loaderData.order.note} />
      <button type="submit">Save</button>
    </Form>
  );
}
```

- `loader` runs on the server; `clientLoader` (with `clientLoader.hydrate = true as const`) runs in the browser and can wrap `serverLoader()` for cache-first reads. `clientAction` mirrors it.
- `HydrateFallback` renders during initial client loading; `shouldRevalidate` opts out of automatic revalidation after actions.
- `middleware` / `clientMiddleware` exports run before loaders — put session checks there and pass the user through context, not in every loader.
- `meta`, `links`, `headers`, `handle` cover document head, HTTP headers and `useMatches` data.

## 4. Data mode in a Vite SPA

```tsx
import { createBrowserRouter, RouterProvider } from 'react-router';

const router = createBrowserRouter([
  { path: '/', lazy: () => import('./routes/home') },              // route-level code splitting
  { path: '/orders/:id', lazy: () => import('./routes/order') },   // module exports loader/action/Component
]);

export function App() {
  return <RouterProvider router={router} />;
}
```

TanStack Query still owns client caching in a SPA; use loaders to prefetch into the query client (`queryClient.ensureQueryData`) so the route renders with data.

## 5. Choosing between Next.js 16 and React Router v8 framework mode

| Need | Next.js 16 | React Router v8 |
|---|---|---|
| Server Components, streaming RSC payloads | Yes, stable | Opt-in, unstable |
| Partial prerendering + explicit caching | Cache Components | Static/SSR per route; caching is yours (CDN headers via `headers`) |
| Vendor-neutral hosting (any Node host, Cloudflare, Deno) | Adapters (alpha) | First-class |
| Mutations | Server Actions | `action` + `<Form>` — progressive enhancement built in |
| Bundle control | Turbopack, limited config | Plain Vite |

Flip to React Router when hosting portability or Vite control outranks RSC; flip to Next.js when RSC, image optimisation and PPR are hard requirements.
