Org Skills

React Router v8 — framework and data mode

Supporting material for react-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

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)

// 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

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.