React Router Framework Mode

React Router Framework Mode

Framework mode is React Router's full-stack development experience with file-based routing, server-side, client-side, and static rendering strategies, data loading and mutations, and type-safe route module API.

When to Apply

• Configuring new routes (app/routes.ts)
• Loading data with loader or clientLoader
• Handling mutations with action or clientAction
• Navigating with <Link>, <NavLink>, <Form>, redirect, and useNavigate
• Implementing pending/loading UI states
• Configuring SSR, SPA mode, or pre-rendering (react-router.config.ts)
• Implementing authentication

References

Load the relevant reference for detailed guidance on the specific API/concept:

Version Compatibility

Some features require specific React Router versions. Always verify before implementing:

npm list react-router

Critical Patterns

These are the most important patterns to follow. Load the relevant reference for full details.

Forms & Mutations

Search forms - use <Form method="get">, NOT onSubmit with setSearchParams:

// ✅ Correct
<Form method="get">
  <input name="q" />
</Form>

// ❌ Wrong - don't manually handle search params
<form onSubmit={(e) => { e.preventDefault(); setSearchParams(...) }}>

Inline mutations - use useFetcher, NOT <Form> (which causes page navigation):

const fetcher = useFetcher();
const optimistic = fetcher.formData?.get("favorite") === "true" ?? isFavorite;

<fetcher.Form method="post" action={`/favorites/${id}`}>
  <button>{optimistic ? "★" : "☆"}</button>
</fetcher.Form>;

See references/actions.md for complete patterns.

Layouts

Global UI belongs in `root.tsx` - don't create separate layout files for nav/footer:

// app/root.tsx - add navigation, footer, providers here
export default function App() {
  return (
    <div>
      <nav>...</nav>
      <Outlet />
      <footer>...</footer>
    </div>
  );
}

Use nested routes for section-specific layouts. See references/routing.md.

Route Module Exports

`meta` uses `loaderData`, not deprecated data:

// ✅ Correct
export function meta({ loaderData }: Route.MetaArgs) { ... }

// ❌ Wrong - `data` is deprecated
export function meta({ data }: Route.MetaArgs) { ... }

See references/route-modules.md for all exports.

Further Documentation

If anything related to React Router is not covered in these references, you can search the official documentation:

https://reactrouter.com/docs

Actions and Form Handling

Actions handle data mutations (create, update, delete). After an action completes, all loaders on the page automatically revalidate.

Choosing the Right Pattern

Default to `useFetcher` for mutations - it provides smoother UX with optimistic updates and no page reload.

Anti-Patterns to Avoid

// ❌ DON'T: Manual form handling for search
function SearchForm() {
  const [searchParams, setSearchParams] = useSearchParams();

  function onSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    setSearchParams({ q: formData.get("q") as string });
  }

  return (
    <form onSubmit={onSubmit}>
      <input name="q" />
      <button type="submit">Search</button>
    </form>
  );
}

// ✅ DO: Use Form with method="get" - handles search params automatically
function SearchForm() {
  return (
    <Form method="get">
      <input name="q" />
      <button type="submit">Search</button>
    </Form>
  );
}

// ❌ DON'T: Use Form for inline mutations (causes full navigation)
function RatingButton({ itemId }) {
  return (
    <Form method="post" action={`/items/${itemId}/rate`}>
      <button>Rate</button>
    </Form>
  );
}

// ✅ DO: Use useFetcher for inline mutations (no navigation, smoother UX)
function RatingButton({ itemId, currentRating }) {
  const fetcher = useFetcher();

  // Optimistic UI - show expected state immediately
  const optimisticRating = fetcher.formData
    ? Number(fetcher.formData.get("rating"))
    : currentRating;

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/rate`}>
      <input type="hidden" name="rating" value={optimisticRating + 1} />
      <button>⭐ {optimisticRating}</button>
    </fetcher.Form>
  );
}

---

Search Forms with GET

<Form method="get"> automatically serializes inputs to URL search params:

import { Form, useSearchParams } from "react-router";

export default function SearchPage() {
  const [searchParams] = useSearchParams();
  const query = searchParams.get("q") ?? "";

  return (
    <div>
      <Form method="get">
        <input type="text" name="q" defaultValue={query} />
        <button type="submit">Search</button>
      </Form>
      {/* Results render here */}
    </div>
  );
}

// Loader receives search params via request.url
export async function loader({ request }: Route.LoaderArgs) {
  const url = new URL(request.url);
  const query = url.searchParams.get("q") ?? "";
  return { results: await search(query) };
}

---

Server Action

Runs on the server:

import { redirect, data } from "react-router";

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const title = formData.get("title");

  await db.createProject({ title });

  return redirect("/projects");
}

Client Action

Runs in the browser:

export async function clientAction({
  request,
  serverAction,
}: Route.ClientActionArgs) {
  const formData = await request.formData();

  // Can call server action
  const result = await serverAction();

  // Or handle entirely on client
  await clientApi.update(formData);

  return result;
}

---

Form Component

The <Form> component submits to actions and handles navigation:

import { Form } from "react-router";

export default function NewProject() {
  return (
    <Form method="post">
      <input type="text" name="title" required />
      <button type="submit">Create</button>
    </Form>
  );
}

Form Props

• method - HTTP method: "get", "post", "put", "delete", "patch"
• action - URL to submit to (defaults to current route)
• navigate - Set to false to prevent navigation after submission

<Form method="post" action="/projects/new">
  {/* ... */}
</Form>

useSubmit

Submit forms programmatically:

import { useSubmit } from "react-router";

function AutoSave({ data }) {
  const submit = useSubmit();

  useEffect(() => {
    const timeout = setTimeout(() => {
      submit(data, { method: "post" });
    }, 1000);

    return () => clearTimeout(timeout);
  }, [data, submit]);

  return null;
}

useFetcher (Preferred for Mutations)

Use `useFetcher` as the default for mutations - it provides independent state, no page navigation, and enables optimistic UI.

Basic Usage

import { useFetcher } from "react-router";

function LikeButton({ postId }) {
  const fetcher = useFetcher();
  const isLiking = fetcher.state === "submitting";

  return (
    <fetcher.Form method="post" action={`/posts/${postId}/like`}>
      <button disabled={isLiking}>{isLiking ? "Liking..." : "Like"}</button>
    </fetcher.Form>
  );
}

Optimistic UI Pattern (Recommended)

Use fetcher.formData to show expected results immediately. See pending-ui.md for complete patterns.

Quick example:

function FavoriteButton({ itemId, isFavorite }) {
  const fetcher = useFetcher();

  // Optimistic: use pending form data, fallback to server state
  const optimistic = fetcher.formData
    ? fetcher.formData.get("favorite") === "true"
    : isFavorite;

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/favorite`}>
      <input type="hidden" name="favorite" value={String(!optimistic)} />
      <button>{optimistic ? "★" : "☆"}</button>
    </fetcher.Form>
  );
}

Typing useFetcher

See type-safety.md for typing patterns.

Fetcher Properties

• fetcher.state - "idle", "submitting", or "loading"
• fetcher.data - Data returned from the action
• fetcher.formData - FormData being submitted (use for optimistic UI)
• fetcher.Form - Form component scoped to this fetcher
• fetcher.submit() - Submit programmatically

Returning Data from Actions

Return data for the UI to use:

import { data } from "react-router";

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const email = formData.get("email");

  const errors: Record<string, string> = {};

  if (!email?.toString().includes("@")) {
    errors.email = "Invalid email address";
  }

  if (Object.keys(errors).length > 0) {
    return data({ errors }, { status: 400 });
  }

  await createUser({ email });
  return redirect("/dashboard");
}

Access action data with fetcher.data:

function SignupForm() {
  const fetcher = useFetcher();
  const errors = fetcher.data?.errors;

  return (
    <fetcher.Form method="post">
      <input type="email" name="email" />
      {errors?.email && <span>{errors.email}</span>}
      <button type="submit">Sign Up</button>
    </fetcher.Form>
  );
}

Form Validation Pattern

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const email = String(formData.get("email"));
  const password = String(formData.get("password"));

  const errors: Record<string, string> = {};

  if (!email.includes("@")) {
    errors.email = "Invalid email address";
  }

  if (password.length < 12) {
    errors.password = "Password must be at least 12 characters";
  }

  if (Object.keys(errors).length > 0) {
    return data({ errors }, { status: 400 });
  }

  // Validation passed
  await createAccount({ email, password });
  return redirect("/dashboard");
}

Multiple Actions per Route

Use a hidden input or button name to distinguish intents:

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const intent = formData.get("intent");

  switch (intent) {
    case "update":
      return updateProject(formData);
    case "delete":
      return deleteProject(formData);
    default:
      throw new Response("Invalid intent", { status: 400 });
  }
}

// In component
<Form method="post">
  <button name="intent" value="update">
    Save
  </button>
  <button name="intent" value="delete">
    Delete
  </button>
</Form>;

---

See Also

• pending-ui.md - Optimistic UI and loading states
• type-safety.md - Typing useFetcher and actions
• route-modules.md - All route module exports

Data Loading

Data is loaded using loader (server) and clientLoader (browser) functions.

Server Loader

Runs on the server during SSR and on server during client navigation:

export async function loader({ params, request }: Route.LoaderArgs) {
  const product = await db.getProduct(params.id);
  return product;
}

export default function Product({ loaderData }: Route.ComponentProps) {
  return <h1>{loaderData.name}</h1>;
}

LoaderArgs

• params - URL parameters from dynamic segments
• request - The Fetch Request object
• context - App context passed from server entry

Client Loader

Runs in the browser. Useful for:

• Skipping the server hop (calling APIs directly)
• Combining server and client data
• Client-side caching

export async function clientLoader({ params }: Route.ClientLoaderArgs) {
  const res = await fetch(`/api/products/${params.id}`);
  return res.json();
}

Combining Server and Client Loaders

export async function loader({ params }: Route.LoaderArgs) {
  return db.getProduct(params.id);
}

export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) {
  // Get server data
  const serverData = await serverLoader();

  // Add client-only data
  const preferences = localStorage.getItem("prefs");

  return { ...serverData, preferences: JSON.parse(preferences || "{}") };
}

Hydration with Client Loader

Force clientLoader to run during initial page hydration:

export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) {
  const cached = getFromCache();
  if (cached) return cached;

  const data = await serverLoader();
  setInCache(data);
  return data;
}

// This enables the clientLoader to run on hydration
clientLoader.hydrate = true;

// Show fallback while clientLoader runs
export function HydrateFallback() {
  return <ProductSkeleton />;
}

Returning Responses

Loaders can return plain objects or Response objects:

export async function loader({ params }: Route.LoaderArgs) {
  const product = await db.getProduct(params.id);

  if (!product) {
    throw new Response("Not Found", { status: 404 });
  }

  return product;
}

Throwing Redirects

Redirect from loaders using redirect:

import { redirect } from "react-router";

export async function loader({ request }: Route.LoaderArgs) {
  const user = await getUser(request);

  if (!user) {
    throw redirect("/login");
  }

  return user;
}

Using Request

Access headers, URL, and signal from the request:

export async function loader({ request }: Route.LoaderArgs) {
  const url = new URL(request.url);
  const query = url.searchParams.get("q");

  // Use abort signal for cancellation
  const results = await search(query, { signal: request.signal });

  return results;
}

Parallel Data Loading

React Router loads data for all matched routes in parallel. Parent and child loaders run simultaneously, not sequentially.

Streaming with defer (Advanced)

Stream slow data while rendering fast data immediately:

import { defer, Await } from "react-router";
import { Suspense } from "react";

export async function loader({ params }: Route.LoaderArgs) {
  return {
    product: await db.getProduct(params.id), // Await immediately
    reviews: db.getReviews(params.id), // Don't await - stream later
  };
}

export default function Product({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <h1>{loaderData.product.name}</h1>

      <Suspense fallback={<ReviewsSkeleton />}>
        <Await resolve={loaderData.reviews}>
          {(reviews) => <Reviews items={reviews} />}
        </Await>
      </Suspense>
    </div>
  );
}

Error Handling

React Router catches errors in loaders, actions, and rendering, then displays them in error boundaries.

ErrorBoundary Export

Export an ErrorBoundary from any route module:

import { isRouteErrorResponse, useRouteError } from "react-router";

export function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>
          {error.status} {error.statusText}
        </h1>
        <p>{error.data}</p>
      </div>
    );
  }

  if (error instanceof Error) {
    return (
      <div>
        <h1>Error</h1>
        <p>{error.message}</p>
        {process.env.NODE_ENV === "development" && <pre>{error.stack}</pre>}
      </div>
    );
  }

  return <h1>Unknown Error</h1>;
}

Throwing Responses

Throw Response objects for expected errors:

export async function loader({ params }: Route.LoaderArgs) {
  const product = await db.getProduct(params.id);

  if (!product) {
    throw new Response("Product not found", { status: 404 });
  }

  return product;
}

Use the data helper for structured error data:

import { data } from "react-router";

export async function loader({ params }: Route.LoaderArgs) {
  const product = await db.getProduct(params.id);

  if (!product) {
    throw data(
      { message: "Product not found", productId: params.id },
      { status: 404 },
    );
  }

  return product;
}

isRouteErrorResponse

Check if an error is a Response thrown from a loader/action:

import { isRouteErrorResponse, useRouteError } from "react-router";

export function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    // This was a Response thrown intentionally
    // error.status, error.statusText, error.data are available
    return <NotFoundPage />;
  }

  // This was an unexpected error
  return <GenericErrorPage />;
}

Error Bubbling

Errors bubble up to the nearest ErrorBoundary:

root.tsx (has ErrorBoundary)
└── products.tsx (no ErrorBoundary)
    └── product.$id.tsx (has ErrorBoundary)

• Error in product.$id.tsx → caught by product.$id.tsx
• Error in products.tsx → caught by root.tsx

Root Error Boundary

Always define an ErrorBoundary in your root route as a last resort:

// app/root.tsx
export function ErrorBoundary() {
  const error = useRouteError();

  return (
    <html>
      <head>
        <title>Oops!</title>
      </head>
      <body>
        <h1>Something went wrong</h1>
        {isRouteErrorResponse(error) ? (
          <p>
            {error.status}: {error.data}
          </p>
        ) : (
          <p>An unexpected error occurred</p>
        )}
      </body>
    </html>
  );
}

Error Reporting

Report errors to a logging service in entry.server.tsx:

// app/entry.server.tsx
import type { HandleErrorFunction } from "react-router";

export const handleError: HandleErrorFunction = (error, { request }) => {
  // Don't log aborted requests
  if (request.signal.aborted) {
    return;
  }

  // Report to your error tracking service
  reportErrorToService(error);

  // Always log for debugging
  console.error(error);
};

Reveal the server entry if it doesn't exist:

npx react-router reveal entry.server

Validation Errors (Not Error Boundaries)

For form validation, return errors from the action instead of throwing:

import { data } from "react-router";

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const email = formData.get("email")?.toString() ?? "";

  if (!email.includes("@")) {
    return data({ errors: { email: "Invalid email" } }, { status: 400 });
  }

  // Success
  await createUser({ email });
  return redirect("/welcome");
}

Access in component via fetcher.data:

function SignupForm() {
  const fetcher = useFetcher();
  const errors = fetcher.data?.errors;

  return (
    <fetcher.Form method="post">
      <input type="email" name="email" />
      {errors?.email && <span className="error">{errors.email}</span>}
      <button>Sign Up</button>
    </fetcher.Form>
  );
}

Production vs Development

In production, error messages are sanitized to prevent leaking sensitive info. Full error details are only shown in development.

Middleware & Context API

⚠️ Version Requirements - Check First!

Before implementing middleware, verify your React Router version:

npm list react-router

If your version is below 7.9.0:

• Middleware is not available
• Use loaders/actions for request processing instead
• Or upgrade: npm install react-router@latest

Enabling Middleware

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  future: {
    v8_middleware: true, // Required for middleware
  },
} satisfies Config;

See https://reactrouter.com/how-to/middleware#changes-to-getloadcontextapploadcontext for migration instructions.

Overview

Middleware runs code before and after response generation. Executes in a nested chain: parent → child on the way down, child → parent on the way up.

Root middleware start
  Parent middleware start
    Child middleware start
      → Run loaders, generate Response
    Child middleware end
  Parent middleware end
Root middleware end

Basic Middleware

import type { Route } from "./+types/dashboard";
import { redirect } from "react-router";

async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
  const user = await getUserFromSession(request);
  if (!user) {
    throw redirect("/login");
  }
  context.set(userContext, user);
}

export const middleware: Route.MiddlewareFunction[] = [authMiddleware];

The next Function

Call next() to continue the chain and get the response:

async function loggingMiddleware(
  { request }: Route.MiddlewareArgs,
  next: Route.MiddlewareNext,
) {
  console.log(`→ ${request.method} ${request.url}`);

  const response = await next();

  console.log(`← ${response.status}`);
  return response;
}

• Call next() only once
• If you don't need post-processing, skip calling next() (called automatically)
• next() never throws—errors return as error responses

Context API

Create typed context to share data between middleware and loaders/actions:

// app/context.ts
import { createContext } from "react-router";

export const userContext = createContext<User | null>(null);
export const dbContext = createContext<Database>();

Setting Context in Middleware

import { userContext } from "~/context";

async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
  const user = await getUser(request);
  context.set(userContext, user);
}

export const middleware: Route.MiddlewareFunction[] = [authMiddleware];

Reading Context in Loaders/Actions

import { userContext } from "~/context";

export async function loader({ context }: Route.LoaderArgs) {
  const user = context.get(userContext);
  return { profile: await getProfile(user) };
}

export async function action({ context }: Route.ActionArgs) {
  const user = context.get(userContext);
  // user is available here too
}

Server vs Client Middleware

Server middleware (middleware) runs on document requests and .data fetches:

export const middleware: Route.MiddlewareFunction[] = [
  async ({ request, context }, next) => {
    // Runs on server
    const response = await next();
    return response;
  },
];

Client middleware (clientMiddleware) runs on client-side navigations:

export const clientMiddleware: Route.ClientMiddlewareFunction[] = [
  async ({ context }, next) => {
    // Runs in browser
    const start = performance.now();
    await next();
    console.log(`Navigation: ${performance.now() - start}ms`);
  },
];

When Server Middleware Runs

To force middleware on routes without loaders, add an empty loader:

export const middleware: Route.MiddlewareFunction[] = [authMiddleware];

export async function loader() {
  return null;
}

Common Patterns

Authentication

async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
  const session = await getSession(request);
  if (!session.get("userId")) {
    throw redirect("/login");
  }
  context.set(userContext, await getUserById(session.get("userId")));
}

Request Logging

async function loggingMiddleware(
  { request }: Route.MiddlewareArgs,
  next: Route.MiddlewareNext,
) {
  const id = crypto.randomUUID();
  const start = performance.now();

  console.log(`[${id}] ${request.method} ${request.url}`);
  const response = await next();
  console.log(`[${id}] ${response.status} (${performance.now() - start}ms)`);

  return response;
}

Response Headers

async function securityHeaders(
  _: Route.MiddlewareArgs,
  next: Route.MiddlewareNext,
) {
  const response = await next();
  response.headers.set("X-Frame-Options", "DENY");
  response.headers.set("X-Content-Type-Options", "nosniff");
  return response;
}

404 Fallback

async function cmsFallback(
  { request }: Route.MiddlewareArgs,
  next: Route.MiddlewareNext,
) {
  const response = await next();

  if (response.status === 404) {
    const redirect = await checkCmsRedirects(request.url);
    if (redirect) throw redirect(redirect, 302);
  }

  return response;
}

Conditional Execution

export const middleware: Route.MiddlewareFunction[] = [
  async ({ request, context }, next) => {
    if (request.method === "POST") {
      await requireAuth(request, context);
    }
    return next();
  },
];

Error Handling

Errors bubble to the nearest ErrorBoundary. The next() function always returns a response (never throws):

export const middleware: Route.MiddlewareFunction[] = [
  async (_, next) => {
    const response = await next();
    // response.status = 500 if child threw
    // Can still set headers, commit sessions, etc.
    return response;
  },
];

• Error before next(): Bubbles to highest route with a loader
• Error after next(): Bubbles from the throwing route

See Also

• React Router Middleware Documentation

Navigation

React Router provides several ways to navigate between routes.

Link Component

Basic navigation:

import { Link } from "react-router";

function Nav() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <Link to="/products/123">Product</Link>
    </nav>
  );
}

Link Props

• to - Destination path (string or object)
• replace - Replace current history entry instead of pushing
• state - Pass state to the destination
• prefetch - "none", "intent", "render", "viewport"

<Link to="/dashboard" replace state={{ from: "home" }} prefetch="intent">
  Dashboard
</Link>

NavLink Component

Link with active/pending state awareness:

import { NavLink } from "react-router";

function Nav() {
  return (
    <nav>
      <NavLink
        to="/"
        end
        className={({ isActive }) => (isActive ? "active" : "")}
      >
        Home
      </NavLink>

      <NavLink
        to="/products"
        className={({ isActive, isPending }) =>
          isPending ? "pending" : isActive ? "active" : ""
        }
      >
        Products
      </NavLink>
    </nav>
  );
}

NavLink Props

• end - Only match if the path is exact (not just a prefix)
• className - String or function receiving { isActive, isPending }
• style - Object or function receiving { isActive, isPending }
• children - Can be a function receiving { isActive, isPending }

<NavLink to="/messages">
  {({ isActive, isPending }) => (
    <span>Messages {isPending && <Spinner />}</span>
  )}
</NavLink>

useNavigate Hook

Programmatic navigation:

import { useNavigate } from "react-router";

function LogoutButton() {
  const navigate = useNavigate();

  async function handleLogout() {
    await logout();
    navigate("/login");
  }

  return <button onClick={handleLogout}>Logout</button>;
}

Navigate Options

const navigate = useNavigate();

// Basic navigation
navigate("/dashboard");

// Replace history entry
navigate("/login", { replace: true });

// Pass state
navigate("/checkout", { state: { cartId: "abc" } });

// Go back/forward
navigate(-1); // Back
navigate(1); // Forward

redirect Function

Redirect from loaders and actions:

import { redirect } from "react-router";

export async function loader({ request }: Route.LoaderArgs) {
  const user = await getUser(request);

  if (!user) {
    throw redirect("/login");
  }

  return user;
}

export async function action({ request }: Route.ActionArgs) {
  await createProject(request);
  return redirect("/projects");
}

Redirect with Status

// Temporary redirect (302, default)
throw redirect("/new-location");

// Permanent redirect (301)
throw redirect("/new-location", { status: 301 });

Form Navigation

Forms with method="get" navigate with search params:

import { Form } from "react-router";

function SearchForm() {
  return (
    <Form method="get" action="/search">
      <input type="text" name="q" />
      <button type="submit">Search</button>
    </Form>
  );
}
// Navigates to /search?q=...

Relative Navigation

Paths are relative to the current route:

// If current URL is /products/123

<Link to="reviews">     // → /products/123/reviews
<Link to="../456">      // → /products/456
<Link to="..">          // → /products

Use relative="path" for path-based relativity instead of route-based:

<Link to=".." relative="path">

Accessing Location State

Read state passed during navigation:

import { useLocation } from "react-router";

function Checkout() {
  const location = useLocation();
  const { from } = location.state || {};

  return (
    <div>
      <h1>Checkout</h1>
      {from && <Link to={from}>Go back</Link>}
    </div>
  );
}

Scroll Restoration

<ScrollRestoration /> (in root) handles scroll position automatically.

Prevent scroll reset on specific links:

<Link to="/products" preventScrollReset>
  Products
</Link>

Pending UI and Optimistic Updates

Key principle: Show expected results immediately using fetcher.formData, then let React Router sync with the server.

Quick Reference

For mutation patterns (when to use Form vs useFetcher), see actions.md.

---

useNavigation

Track global navigation state:

import { useNavigation } from "react-router";

export default function Root() {
  const navigation = useNavigation();
  const isNavigating = Boolean(navigation.location);

  return (
    <html>
      <body className={isNavigating ? "loading" : ""}>
        {isNavigating && <GlobalSpinner />}
        <Outlet />
      </body>
    </html>
  );
}

Navigation States

• navigation.state - "idle", "loading", or "submitting"
• navigation.location - The location being navigated to (if any)
• navigation.formData - Form data being submitted (if any)
• navigation.formMethod - HTTP method of the submission

const navigation = useNavigation();

// Check if navigating
const isNavigating = navigation.state !== "idle";

// Check if submitting a form
const isSubmitting = navigation.state === "submitting";

// Check if loading after submission
const isLoading = navigation.state === "loading";

NavLink Pending State

Show pending state on the specific link being clicked:

import { NavLink } from "react-router";

function Nav() {
  return (
    <NavLink to="/dashboard">
      {({ isPending }) => <span>Dashboard {isPending && <Spinner />}</span>}
    </NavLink>
  );
}

Or use className:

<NavLink
  to="/dashboard"
  className={({ isPending }) => (isPending ? "pending" : "")}
>
  Dashboard
</NavLink>

useFetcher for Local State

Each fetcher tracks its own state independently:

import { useFetcher } from "react-router";

function LikeButton({ postId, liked }) {
  const fetcher = useFetcher();

  // Show pending state while submitting
  const isPending = fetcher.state !== "idle";

  return (
    <fetcher.Form method="post" action={`/posts/${postId}/like`}>
      <button disabled={isPending}>
        {isPending ? "..." : liked ? "Unlike" : "Like"}
      </button>
    </fetcher.Form>
  );
}

Fetcher States

• fetcher.state - "idle", "submitting", or "loading"
• fetcher.data - Data returned from the action/loader
• fetcher.formData - Form data being submitted

Optimistic UI with useFetcher (Recommended Pattern)

This is the standard pattern for mutations. Show the expected result immediately using fetcher.formData:

import { useFetcher } from "react-router";

function LikeButton({ postId, initialLiked }) {
  const fetcher = useFetcher();

  // Optimistic: check pending form data first, fallback to server state
  const liked = fetcher.formData
    ? fetcher.formData.get("liked") === "true"
    : initialLiked;

  return (
    <fetcher.Form method="post" action={`/posts/${postId}/like`}>
      <input type="hidden" name="liked" value={String(!liked)} />
      <button>{liked ? "❤️" : "🤍"}</button>
    </fetcher.Form>
  );
}

Complete Optimistic UI Example

import { useFetcher } from "react-router";

function RatingStars({ itemId, currentRating }) {
  const fetcher = useFetcher();

  // 1. Check if we're submitting - use the pending value
  // 2. Otherwise use the server value
  const displayRating = fetcher.formData
    ? Number(fetcher.formData.get("rating"))
    : currentRating;

  const isSubmitting = fetcher.state !== "idle";

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/rate`}>
      <div style={{ opacity: isSubmitting ? 0.5 : 1 }}>
        {[1, 2, 3, 4, 5].map((star) => (
          <button key={star} type="submit" name="rating" value={star}>
            {star <= displayRating ? "★" : "☆"}
          </button>
        ))}
      </div>
    </fetcher.Form>
  );
}

Why fetcher.formData?

• Instant feedback - UI updates immediately on click
• No loading spinners needed - the optimistic state IS the loading state
• Automatic rollback - if the action fails, loaders revalidate and reset to server state

Optimistic UI with useNavigation

For form submissions that navigate:

import { Form, useNavigation } from "react-router";

function NewProjectForm() {
  const navigation = useNavigation();

  // Get optimistic value from submission
  const optimisticTitle = navigation.formData?.get("title");
  const isSubmitting = navigation.state === "submitting";

  return (
    <Form method="post">
      <input type="text" name="title" />
      <button disabled={isSubmitting}>
        {isSubmitting ? "Creating..." : "Create"}
      </button>

      {optimisticTitle && <p>Creating "{optimisticTitle}"...</p>}
    </Form>
  );
}

Skeleton Loading

Show skeletons while data loads:

import { Suspense } from "react";
import { Await } from "react-router";

export async function loader() {
  return {
    fastData: await getFastData(),
    slowData: getSlowData(), // Don't await
  };
}

export default function Page({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <h1>{loaderData.fastData.title}</h1>

      <Suspense fallback={<CommentsSkeleton />}>
        <Await resolve={loaderData.slowData}>
          {(data) => <Comments data={data} />}
        </Await>
      </Suspense>
    </div>
  );
}

Disabling During Submission

Prevent double submissions:

function ContactForm() {
  const navigation = useNavigation();
  const isSubmitting = navigation.state === "submitting";

  return (
    <Form method="post">
      <input type="text" name="message" disabled={isSubmitting} />
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Sending..." : "Send"}
      </button>
    </Form>
  );
}

Busy Indicators with CSS

Use CSS for simple loading indicators:

.loading {
  opacity: 0.5;
  pointer-events: none;
}

<body className={isNavigating ? "loading" : ""}>

---

See Also

• actions.md - Form handling and useFetcher patterns
• special-files.md - Global loading indicators in root.tsx

Rendering Strategies

React Router supports three rendering strategies, configured in react-router.config.ts.

Server-Side Rendering (SSR)

Default mode. Pages are rendered on the server for each request:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  ssr: true, // default
} satisfies Config;

How it works:

1. Server runs loaders and renders HTML 2. HTML is sent to browser 3. Browser hydrates with JavaScript 4. Subsequent navigations are client-side

When to use:

• Dynamic content that changes per request
• SEO-critical pages
• Content that depends on user authentication

Client-Side Rendering (SPA Mode)

Disable SSR for a single-page application:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  ssr: false,
} satisfies Config;

How it works:

1. Server sends minimal HTML shell 2. Browser loads JavaScript 3. JavaScript renders the app and fetches data

When to use:

• Apps behind authentication (no SEO needed)
• Dashboards and admin panels
• When you can't run a Node.js server

In SPA mode, use clientLoader instead of loader:

export async function clientLoader({ params }: Route.ClientLoaderArgs) {
  const res = await fetch(`/api/products/${params.id}`);
  return res.json();
}

Static Pre-rendering

Generate static HTML at build time:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  ssr: true,
  prerender: true, // Pre-render all static routes
} satisfies Config;

Pre-render Specific Paths

export default {
  ssr: true,
  prerender: ["/", "/about", "/pricing"],
} satisfies Config;

Pre-render Dynamic Paths

Use an async function:

export default {
  ssr: true,
  async prerender() {
    const products = await db.getAllProducts();
    return ["/", "/about", ...products.map((p) => `/products/${p.id}`)];
  },
} satisfies Config;

How it works:

1. At build time, routes are rendered to static HTML 2. Static HTML files are deployed 3. Browser hydrates with JavaScript 4. Subsequent navigations are client-side

When to use:

• Marketing pages, blogs, documentation
• Content that doesn't change per request
• Maximum performance and CDN caching

SPA Fallback

When using ssr: false, a fallback HTML file is generated for routes not pre-rendered:

export default {
  ssr: false,
  prerender: ["/", "/about"], // These are pre-rendered
  // Other routes use the SPA fallback
} satisfies Config;

Mixing Strategies

You can combine pre-rendering with SSR:

export default {
  ssr: true,
  prerender: ["/", "/about", "/pricing"],
  // Other routes are server-rendered
} satisfies Config;

Pre-rendered routes serve static HTML. Other routes are rendered on the server.

Route-Level Data Loading

The rendering strategy affects which loaders run where:

Configuration Reference

import type { Config } from "@react-router/dev/config";

export default {
  // Enable/disable server rendering
  ssr: true,

  // Pre-render routes at build time
  prerender: true | string[] | (() => Promise<string[]>),

  // Base path for the app
  basename: "/app",

  // Build directory
  buildDirectory: "build",

} satisfies Config;

Route Modules

Route modules are files referenced in routes.ts that define automatic code-splitting, data loading, actions, revalidation, error boundaries, and more. For routing configuration, see routing.md.

Exports Quick Reference

---

Component (default)

The default export renders when the route matches:

import type { Route } from "./+types/my-route";

export default function MyRoute({
  loaderData,
  actionData,
  params,
  matches,
}: Route.ComponentProps) {
  return <div>{loaderData.message}</div>;
}

Props available:

• loaderData - Data from loader
• actionData - Data from action
• params - Route parameters
• matches - All matches in current route tree

---

loader

Loads data on the server before render:

export async function loader({ params, request }: Route.LoaderArgs) {
  const data = await db.find(params.id);
  if (!data) {
    throw new Response("Not Found", { status: 404 });
  }
  return data;
}

Args: { params, request, context }

---

clientLoader

Runs in browser. Can augment or replace server loader:

export async function clientLoader({
  params,
  serverLoader,
}: Route.ClientLoaderArgs) {
  const serverData = await serverLoader();
  const clientData = await getClientData();
  return { ...serverData, ...clientData };
}

// Run during initial hydration
clientLoader.hydrate = true as const;

Args: { params, request, serverLoader }

Use `clientLoader.hydrate = true` when:

• Client loader should run during initial page load
• Need to augment server data with client-only data

---

action

Handles form submissions with automatic revalidation:

import { Form, redirect } from "react-router";

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  await db.create({ title: formData.get("title") });
  return redirect("/list");
}

export default function NewItem() {
  return (
    <Form method="post">
      <input name="title" />
      <button type="submit">Create</button>
    </Form>
  );
}

Args: { params, request, context }

---

clientAction

Handles mutations in the browser:

export async function clientAction({
  request,
  serverAction,
}: Route.ClientActionArgs) {
  invalidateClientCache();
  return await serverAction();
}

Args: { params, request, serverAction }

---

middleware

Runs before/after document and data requests on the server:

export const middleware: Route.MiddlewareFunction[] = [
  async function auth({ request, context }, next) {
    const session = await getSession(request);
    if (!session.userId) {
      throw redirect("/login");
    }
    context.set(userContext, await getUser(session.userId));
    return next();
  },
];

Args: { request, params, context }, next

See middleware reference for details.

---

clientMiddleware

Same as middleware but runs in browser. No Response returned:

export const clientMiddleware: Route.ClientMiddlewareFunction[] = [
  async function timing({ request }, next) {
    const start = performance.now();
    await next();
    console.log(`${request.url} - ${performance.now() - start}ms`);
  },
];

---

ErrorBoundary

Renders when loader, action, or component throws:

import { isRouteErrorResponse, useRouteError } from "react-router";

export function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>
          {error.status} {error.statusText}
        </h1>
        <p>{error.data}</p>
      </div>
    );
  }

  if (error instanceof Error) {
    return (
      <div>
        <h1>Error</h1>
        <p>{error.message}</p>
      </div>
    );
  }

  return <h1>Unknown Error</h1>;
}

---

HydrateFallback

Renders during initial load while clientLoader.hydrate runs:

export async function clientLoader() {
  return await loadLocalData();
}
clientLoader.hydrate = true as const;

export function HydrateFallback() {
  return <div>Loading...</div>;
}

---

headers

Sets HTTP response headers:

export function headers({ loaderHeaders }: Route.HeadersArgs) {
  return {
    "Cache-Control": loaderHeaders.get("Cache-Control") ?? "max-age=3600",
    "X-Custom-Header": "value",
  };
}

---

meta

export function meta({ loaderData }: Route.MetaArgs) {
  return [
    { title: loaderData.product.name },
    { name: "description", content: loaderData.product.description },
  ];
}

Use `loaderData`, not `data` - the data parameter is deprecated.

---

links

Adds <link> elements to document head:

export function links() {
  return [
    { rel: "stylesheet", href: "/styles/page.css" },
    { rel: "preload", href: "/images/hero.jpg", as: "image" },
    { rel: "icon", href: "/favicon.png", type: "image/png" },
  ];
}

---

handle

Custom data accessible via useMatches:

export const handle = {
  breadcrumb: "Dashboard",
  permissions: ["admin"],
};

Usage:

import { useMatches } from "react-router";

function Breadcrumbs() {
  const matches = useMatches();
  const crumbs = matches
    .filter((m) => m.handle?.breadcrumb)
    .map((m) => m.handle.breadcrumb);
  return <nav>{crumbs.join(" > ")}</nav>;
}

---

shouldRevalidate

Opt out of automatic loader revalidation:

export function shouldRevalidate({
  currentUrl,
  nextUrl,
  formMethod,
  defaultShouldRevalidate,
}: Route.ShouldRevalidateFunctionArgs) {
  // Skip for query-only changes
  if (currentUrl.pathname === nextUrl.pathname) {
    return false;
  }
  return defaultShouldRevalidate;
}

---

Complete Example

import type { Route } from "./+types/team";
import {
  Form,
  redirect,
  isRouteErrorResponse,
  useRouteError,
} from "react-router";

export const middleware: Route.MiddlewareFunction[] = [
  async function requireAuth({ context }, next) {
    if (!context.get(userContext)) throw redirect("/login");
    return next();
  },
];

export async function loader({ params }: Route.LoaderArgs) {
  const team = await db.teams.find(params.teamId);
  if (!team) throw new Response("Not Found", { status: 404 });
  return { team };
}

export async function action({ request, params }: Route.ActionArgs) {
  const formData = await request.formData();
  await db.teams.update(params.teamId, { name: formData.get("name") });
  return { success: true };
}

export function headers() {
  return { "Cache-Control": "private, max-age=60" };
}

export default function Team({ loaderData, actionData }: Route.ComponentProps) {
  return (
    <div>
      <title>{loaderData.team.name}</title>
      <h1>{loaderData.team.name}</h1>
      {actionData?.success && <p>Updated!</p>}
      <Form method="post">
        <input name="name" defaultValue={loaderData.team.name} />
        <button type="submit">Update</button>
      </Form>
    </div>
  );
}

export function ErrorBoundary() {
  const error = useRouteError();
  if (isRouteErrorResponse(error) && error.status === 404) {
    return <h1>Team not found</h1>;
  }
  return <h1>Something went wrong</h1>;
}

See Also

• Route Module Documentation

Routing

For file conventions (root.tsx, routes.ts, etc.), see special-files.md.

If using @react-router/fs-routes see https://reactrouter.com/how-to/file-route-conventions

Route Configuration

Routes are configured in app/routes.ts. Each route has a URL pattern and a file path to the route module:

import { type RouteConfig, route } from "@react-router/dev/routes";

export default [
  route("some/path", "./some/file.tsx"),
  // pattern ^           ^ module file
] satisfies RouteConfig;

Complete Example

import {
  type RouteConfig,
  route,
  index,
  layout,
  prefix,
} from "@react-router/dev/routes";

export default [
  index("./home.tsx"),
  route("about", "./about.tsx"),

  layout("./auth/layout.tsx", [
    route("login", "./auth/login.tsx"),
    route("register", "./auth/register.tsx"),
  ]),

  ...prefix("concerts", [
    index("./concerts/home.tsx"),
    route(":city", "./concerts/city.tsx"),
    route("trending", "./concerts/trending.tsx"),
  ]),
] satisfies RouteConfig;

Combining with File-Based Routes

import { type RouteConfig, route } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";

export default [
  route("/", "./home.tsx"),
  ...(await flatRoutes()),
] satisfies RouteConfig;

Route Helpers

Nested Routes

Child routes are passed as the third argument:

export default [
  route("dashboard", "./dashboard.tsx", [
    index("./dashboard-home.tsx"),
    route("settings", "./dashboard-settings.tsx"),
  ]),
] satisfies RouteConfig;

Parent path is automatically included: creates /dashboard and /dashboard/settings.

Outlet

Child routes render through <Outlet /> in the parent:

import { Outlet } from "react-router";

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Outlet />
    </div>
  );
}

Root Route

Every route in `routes.ts` is nested inside `app/root.tsx`. Put global navigation, footer, providers, and fonts there.

See special-files.md for root.tsx customization patterns.

Layout Routes (Use Them!)

Prefer nested routes over flat structures. Layouts reduce code duplication and enable shared UI.

Create nesting without adding URL segments:

export default [
  layout("./marketing/layout.tsx", [
    index("./marketing/home.tsx"), // renders at /
    route("contact", "./marketing/contact.tsx"), // renders at /contact
  ]),
] satisfies RouteConfig;

Both routes render into marketing/layout.tsx's <Outlet />.

Anti-Pattern: Flat Routes

// ❌ DON'T: Flat structure with no shared layouts
export default [
  route("dashboard", "./dashboard.tsx"),
  route("dashboard/settings", "./dashboard-settings.tsx"),
  route("dashboard/profile", "./dashboard-profile.tsx"),
] satisfies RouteConfig;

// ✅ DO: Use nested routes with shared layout
export default [
  route("dashboard", "./dashboard/layout.tsx", [
    index("./dashboard/index.tsx"),
    route("settings", "./dashboard/settings.tsx"),
    route("profile", "./dashboard/profile.tsx"),
  ]),
] satisfies RouteConfig;

Index Routes

Render at the parent's URL (default child):

export default [
  index("./home.tsx"), // renders at /
  route("dashboard", "./dashboard.tsx", [
    index("./dashboard-home.tsx"), // renders at /dashboard
    route("settings", "./settings.tsx"), // renders at /dashboard/settings
  ]),
] satisfies RouteConfig;

Index routes cannot have children.

Route Prefixes

Add a path prefix without introducing a parent route:

export default [
  ...prefix("projects", [
    index("./projects/home.tsx"), // /projects
    route(":pid", "./projects/project.tsx"), // /projects/:pid
  ]),
] satisfies RouteConfig;

Equivalent to:

export default [
  route("projects", "./projects/home.tsx"),
  route("projects/:pid", "./projects/project.tsx"),
] satisfies RouteConfig;

Dynamic Segments

Segments starting with : are dynamic and available via params:

route("teams/:teamId", "./team.tsx");

import type { Route } from "./+types/team";

export async function loader({ params }: Route.LoaderArgs) {
  // params.teamId is typed as string
  return fetchTeam(params.teamId);
}

export default function Team({ params }: Route.ComponentProps) {
  return <h1>Team {params.teamId}</h1>;
}

Multiple dynamic segments:

route("c/:categoryId/p/:productId", "./product.tsx");
// params: { categoryId: string; productId: string }

Optional Segments

Add ? to make a segment optional:

route(":lang?/categories", "./categories.tsx");
// matches /categories and /en/categories

route("users/:userId/edit?", "./user.tsx");
// matches /users/123 and /users/123/edit

Splats (Catch-All)

Match any remaining path with /*:

route("files/*", "./files.tsx");

export async function loader({ params }: Route.LoaderArgs) {
  const filePath = params["*"]; // e.g., "docs/intro.md"
  return getFile(filePath);
}

// Destructure with rename
const { "*": splat } = params;

404 Catch-All

route("*", "./catchall.tsx");

export function loader() {
  throw new Response("Page not found", { status: 404 });
}

See Also

• Route Module - Route module exports
• React Router Routing Documentation

Sessions & Cookies

Overview

React Router provides built-in utilities for cookie-based session management. Always use these instead of hand-rolling cookie implementations.

Session Storage Setup

Create a session storage file that exports the session helpers:

// app/sessions.server.ts
import { createCookieSessionStorage } from "react-router";

type SessionData = {
  userId: string;
};

type SessionFlashData = {
  error: string;
};

const { getSession, commitSession, destroySession } =
  createCookieSessionStorage<SessionData, SessionFlashData>({
    cookie: {
      name: "__session",
      httpOnly: true,
      maxAge: 60 * 60 * 24 * 7, // 1 week
      path: "/",
      sameSite: "lax",
      secrets: [process.env.SESSION_SECRET!],
      secure: process.env.NODE_ENV === "production",
    },
  });

export { getSession, commitSession, destroySession };

Key Points

• `getSession(cookieHeader)` - Parse session from request's Cookie header
• `commitSession(session)` - Generate Set-Cookie header for response
• `destroySession(session)` - Generate Set-Cookie header that clears the session
• Always use `secrets` for signed cookies that can't be tampered with

Getting/Setting Session Data

In Loaders

import type { Route } from "./+types/dashboard";
import { getSession } from "~/sessions.server";

export async function loader({ request }: Route.LoaderArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  const userId = session.get("userId");

  if (!userId) {
    throw redirect("/login");
  }

  return { user: await getUserById(userId) };
}

In Actions

import type { Route } from "./+types/settings";
import { getSession, commitSession } from "~/sessions.server";
import { redirect } from "react-router";

export async function action({ request }: Route.ActionArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  const formData = await request.formData();

  // Update session data
  session.set("theme", formData.get("theme") as string);

  return redirect("/settings", {
    headers: {
      "Set-Cookie": await commitSession(session),
    },
  });
}

Login Route

// app/routes/login.tsx
import { data, redirect, Form } from "react-router";
import type { Route } from "./+types/login";
import { getSession, commitSession } from "~/sessions.server";

export async function loader({ request }: Route.LoaderArgs) {
  const session = await getSession(request.headers.get("Cookie"));

  // Already logged in? Redirect to home
  if (session.has("userId")) {
    return redirect("/");
  }

  return data(
    { error: session.get("error") },
    {
      headers: {
        // Commit to clear flash data
        "Set-Cookie": await commitSession(session),
      },
    },
  );
}

export async function action({ request }: Route.ActionArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  const formData = await request.formData();

  const email = formData.get("email") as string;
  const password = formData.get("password") as string;

  const userId = await validateCredentials(email, password);

  if (!userId) {
    session.flash("error", "Invalid email or password");
    return redirect("/login", {
      headers: {
        "Set-Cookie": await commitSession(session),
      },
    });
  }

  session.set("userId", userId);

  return redirect("/", {
    headers: {
      "Set-Cookie": await commitSession(session),
    },
  });
}

export default function Login({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      {loaderData.error && <p className="error">{loaderData.error}</p>}
      <Form method="post">
        <label>
          Email: <input type="email" name="email" required />
        </label>
        <label>
          Password: <input type="password" name="password" required />
        </label>
        <button type="submit">Log In</button>
      </Form>
    </div>
  );
}

Logout Route

// app/routes/logout.tsx
import { redirect, Form, Link } from "react-router";
import type { Route } from "./+types/logout";
import { getSession, destroySession } from "~/sessions.server";

export async function action({ request }: Route.ActionArgs) {
  const session = await getSession(request.headers.get("Cookie"));

  return redirect("/login", {
    headers: {
      "Set-Cookie": await destroySession(session),
    },
  });
}

export default function Logout() {
  return (
    <div>
      <p>Are you sure you want to log out?</p>
      <Form method="post">
        <button type="submit">Log Out</button>
      </Form>
      <Link to="/">Cancel</Link>
    </div>
  );
}

Important: Always perform logout in an action, never in a loader. This prevents [CSRF attacks][csrf].

Authentication Middleware

Use middleware to set user context from session data, making it available to all child routes.

Setup Context

// app/context.ts
import { createContext } from "react-router";

export type User = {
  id: string;
  email: string;
  name: string;
};

export const userContext = createContext<User | null>(null);

Auth Middleware

// app/routes/auth-middleware.ts (or in a layout route)
import type { Route } from "./+types/auth-middleware";
import { redirect } from "react-router";
import { getSession } from "~/sessions.server";
import { userContext, type User } from "~/context";

async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  const userId = session.get("userId");

  if (userId) {
    const user = await getUserById(userId);
    context.set(userContext, user);
  }
}

export const middleware: Route.MiddlewareFunction[] = [authMiddleware];

Reading User in Loaders

import type { Route } from "./+types/dashboard";
import { userContext } from "~/context";

export async function loader({ context }: Route.LoaderArgs) {
  const user = context.get(userContext);

  if (!user) {
    throw redirect("/login");
  }

  return { user };
}

Protecting Routes with Middleware

For routes that require authentication, use middleware that throws a redirect:

// app/routes/dashboard.tsx
import type { Route } from "./+types/dashboard";
import { redirect } from "react-router";
import { getSession } from "~/sessions.server";
import { userContext } from "~/context";

async function requireAuth({ request, context }: Route.MiddlewareArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  const userId = session.get("userId");

  if (!userId) {
    throw redirect("/login");
  }

  const user = await getUserById(userId);
  context.set(userContext, user);
}

export const middleware: Route.MiddlewareFunction[] = [requireAuth];

export async function loader({ context }: Route.LoaderArgs) {
  const user = context.get(userContext)!; // Safe - middleware guarantees user
  return { projects: await getProjectsForUser(user.id) };
}

Signed Cookies (Low-Level)

For simple cookie data that doesn't need session semantics, use createCookie:

// app/cookies.server.ts
import { createCookie } from "react-router";

export const userPrefs = createCookie("user-prefs", {
  maxAge: 60 * 60 * 24 * 365, // 1 year
  secrets: [process.env.COOKIE_SECRET!],
});

Using in Routes

import { userPrefs } from "~/cookies.server";

export async function loader({ request }: Route.LoaderArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const prefs = (await userPrefs.parse(cookieHeader)) || {};
  return { theme: prefs.theme ?? "light" };
}

export async function action({ request }: Route.ActionArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const prefs = (await userPrefs.parse(cookieHeader)) || {};
  const formData = await request.formData();

  prefs.theme = formData.get("theme");

  return redirect("/", {
    headers: {
      "Set-Cookie": await userPrefs.serialize(prefs),
    },
  });
}

Session Flash Data

Flash data is automatically cleared after being read—useful for one-time messages:

// In action - set flash message
session.flash("success", "Settings saved!");
return redirect("/settings", {
  headers: { "Set-Cookie": await commitSession(session) },
});

// In loader - read and clear flash
const success = session.get("success"); // Returns value, then clears
return data(
  { success },
  { headers: { "Set-Cookie": await commitSession(session) } },
);

Gotcha: With nested routes, multiple loaders run in parallel. If you use flash data, ensure only one loader reads it to avoid race conditions.

Cookie Attributes Reference

createCookieSessionStorage({
  cookie: {
    name: "__session", // Cookie name
    domain: "example.com", // Domain scope
    httpOnly: true, // JS can't access (security)
    maxAge: 60 * 60 * 24, // Expiry in seconds
    path: "/", // URL path scope
    sameSite: "lax", // CSRF protection: "lax" | "strict" | "none"
    secrets: ["secret1"], // Signing secrets (rotate by adding to front)
    secure: true, // HTTPS only (use in production)
  },
});

Secret Rotation

Add new secrets to the front of the array. Old cookies are still readable, new cookies use the first secret:

secrets: ["new-secret", "old-secret"];

See Also

• React Router Sessions & Cookies Documentation
• Session API Reference
• Cookie API Reference
• references/middleware.md - Middleware patterns for auth

[csrf]: https://developer.mozilla.org/en-US/docs/Glossary/CSRF

Special Files

React Router framework mode uses several special files with specific purposes.

Quick Reference

---

root.tsx (Required)

`app/root.tsx` is the only required route - it's the parent to all routes and renders the root <html> document.

What Belongs in root.tsx

Basic root.tsx Structure

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

export default function App() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Using the Layout Export

The Layout export avoids duplicating the document shell across your component, HydrateFallback, and ErrorBoundary:

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

export function ErrorBoundary() {
  return <div>Something went wrong</div>;
}

export function HydrateFallback() {
  return <div>Loading...</div>;
}

Customizing root.tsx (Complete Example)

import {
  Links,
  Meta,
  NavLink,
  Outlet,
  Scripts,
  ScrollRestoration,
  useNavigation,
  useRouteLoaderData,
} from "react-router";
import "./app.css";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        {/* Global fonts go in root.tsx, not layout components */}
        <link rel="preconnect" href="https://fonts.googleapis.com" />
        <link
          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap"
          rel="stylesheet"
        />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  const navigation = useNavigation();
  const isNavigating = navigation.state !== "idle";

  return (
    <div className="app-layout">
      {/* Global loading indicator */}
      {isNavigating && <ProgressBar />}

      {/* Global navigation */}
      <header className="app-header">
        <nav className="app-nav">
          <NavLink
            to="/"
            className={({ isActive }) => (isActive ? "active" : "")}
          >
            Home
          </NavLink>
          <NavLink
            to="/products"
            className={({ isActive }) => (isActive ? "active" : "")}
          >
            Products
          </NavLink>
        </nav>
      </header>

      {/* Page content */}
      <main className="app-main">
        <Outlet />
      </main>

      {/* Global footer */}
      <footer className="app-footer">
        © {new Date().getFullYear()} My App
      </footer>
    </div>
  );
}

Note: Be defensive in your Layout component since it renders the ErrorBoundary. Use useRouteLoaderData("root") instead of useLoaderData to handle cases where the loader threw. See error-handling.md for error boundary patterns.

---

routes.ts (Required)

Defines the URL structure and maps URLs to route modules.

For detailed routing patterns, see [routing.md](./routing.md).

Quick example:

import {
  type RouteConfig,
  route,
  index,
  layout,
} from "@react-router/dev/routes";

export default [
  index("./home.tsx"),
  route("about", "./about.tsx"),
  layout("./dashboard/layout.tsx", [
    route("dashboard", "./dashboard/index.tsx"),
    route("dashboard/settings", "./dashboard/settings.tsx"),
  ]),
] satisfies RouteConfig;

---

react-router.config.ts (Optional)

Configures framework-level settings:

import type { Config } from "@react-router/dev/config";

export default {
  // App directory (default: "app")
  appDirectory: "app",

  // Build output directory (default: "build")
  buildDirectory: "build",

  // Enable/disable SSR (default: true)
  ssr: true,

  // Pre-render routes at build time
  prerender: ["/", "/about", "/pricing"],

  // Base path for all routes
  basename: "/my-app",

  // Future flags
  future: {
    v8_middleware: true,
  },
} satisfies Config;

Common Configuration Options

SPA Mode

Disable SSR for a single-page application:

export default {
  ssr: false,
} satisfies Config;

Pre-rendering

Pre-render routes to static HTML at build time:

export default {
  async prerender({ getStaticPaths }) {
    const dynamicPaths = await getStaticPaths();
    return ["/", "/about", ...dynamicPaths];
  },
} satisfies Config;

---

entry.client.tsx (Optional)

The browser entry point for hydrating server-rendered markup. React Router provides a default, but you can customize it:

npx react-router reveal

import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>,
  );
});

Use cases for customizing:

• Initialize client-side libraries (analytics, error tracking)
• Add client-only providers
• Custom hydration logic

---

entry.server.tsx (Optional)

The server entry point for rendering HTML responses. React Router provides a default for Node, but you may need to customize for other runtimes (Cloudflare, Deno).

npx react-router reveal

import { PassThrough } from "node:stream";
import type { EntryContext } from "react-router";
import { createReadableStreamFromReadable } from "@react-router/node";
import { ServerRouter } from "react-router";
import { renderToPipeableStream } from "react-dom/server";

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  routerContext: EntryContext,
) {
  return new Promise((resolve, reject) => {
    const { pipe, abort } = renderToPipeableStream(
      <ServerRouter context={routerContext} url={request.url} />,
      {
        onShellReady() {
          responseHeaders.set("Content-Type", "text/html");
          const body = new PassThrough();
          const stream = createReadableStreamFromReadable(body);
          resolve(
            new Response(stream, {
              headers: responseHeaders,
              status: responseStatusCode,
            }),
          );
          pipe(body);
        },
        onShellError(error: unknown) {
          reject(error);
        },
      },
    );
  });
}

// Optional: Control streaming timeout
export const streamTimeout = 10000;

// Optional: Handle errors
export function handleError(error: unknown, { request }: { request: Request }) {
  if (!request.signal.aborted) {
    console.error(error);
  }
}

---

.server Modules

Files with .server in the name (e.g., auth.server.ts) are server-only and excluded from client bundles.

app/
├── utils/
│   ├── db.server.ts      # Server-only
│   ├── auth.server.ts    # Server-only
│   └── format.ts         # Shared

Use for:

• Database connections
• Authentication utilities
• Environment variables/secrets
• Server-only APIs

// db.server.ts
import { PrismaClient } from "@prisma/client";

export const db = new PrismaClient();

Safety: The build will fail if .server code accidentally ends up in the client bundle.

Important: Route modules should NOT use .server - they have special handling.

---

.client Modules

Files with .client in the name (e.g., analytics.client.ts) are client-only and excluded from server bundles.

app/
├── utils/
│   ├── analytics.client.ts  # Client-only
│   ├── browser.client.ts    # Client-only
│   └── format.ts            # Shared

Use for:

• Browser-specific APIs (localStorage, navigator)
• Client-only libraries (charting, animations)
• Feature detection

// analytics.client.ts
export function trackEvent(name: string) {
  window.gtag?.("event", name);
}

Note: Values exported from .client modules are undefined on the server. Only use them in useEffect or event handlers.

---

Where to Place Stylesheets and Fonts

Global styles and fonts belong in `root.tsx`, not in layout components:

• Global fonts: In root.tsx <head> (see example above)
• Route-specific stylesheets: Use the links export in route modules (see route-modules.md)

---

Anti-Patterns

Don't create a separate layout just for nav/footer - put global UI in root.tsx.

Don't use flat routes when nesting makes sense - see routing.md for proper nested route patterns.

---

See Also

• routing.md - Route configuration patterns
• route-modules.md - Route module exports
• Official Documentation

Route Module Types

React Router generates route-specific types that provide type inference for URL params, loader data, action data, and more.

Is Typegen Set Up?

Check for these indicators:

1. .react-router/types/ directory exists (or appears after running dev) 2. tsconfig.json includes .react-router/types/**/* 3. Imports like import type { Route } from "./+types/my-route" resolve

If not set up: See https://reactrouter.com/how-to/route-module-type-safety

Importing Types

Import the Route namespace from the +types directory relative to your route file:

import type { Route } from "./+types/my-route";

Available Types

What Gets Typed

Types are inferred from your route configuration:

• URL params: From dynamic segments (:id, :slug)
• Loader data: From loader return → ComponentProps.loaderData
• Action data: From action return → ComponentProps.actionData
• Parent data: Matches include typed data from parent routes

Example

import type { Route } from "./+types/products.$id";

// params.id typed as string (from :id segment)
export async function loader({ params }: Route.LoaderArgs) {
  const product = await db.products.find(params.id);
  return { product };
}

// loaderData.product typed from loader return
export default function Product({ loaderData }: Route.ComponentProps) {
  return <h1>{loaderData.product.name}</h1>;
}

Type-Safe URLs with href

The href utility generates type-safe URL paths:

import { href } from "react-router";

// Type-safe path generation with params
const aboutUrl = href("/:lang?/about", { lang: "en" });
// → "/en/about"

// Use with Link
<Link to={href("/products/:id", { id: "abc123" })} />;

Typing useFetcher

When using useFetcher to call an action from another route, type it with the action's type:

import { useFetcher } from "react-router";

// Option 1: Import the action type directly
import type { action } from "./rate";

function RatingForm({ itemId }: { itemId: string }) {
  const fetcher = useFetcher<typeof action>();

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/rate`}>
      <button name="rating" value="5">
        ⭐⭐⭐⭐⭐
      </button>
      {fetcher.data?.success && <span>Saved!</span>}
    </fetcher.Form>
  );
}

// Option 2: Define inline type for simple cases
type ActionData = { success: boolean; error?: string };

function FavoriteButton({ itemId }: { itemId: string }) {
  const fetcher = useFetcher<ActionData>();

  return (
    <fetcher.Form method="post" action={`/favorites/${itemId}`}>
      <button type="submit">Favorite</button>
    </fetcher.Form>
  );
}

See Also

• Route Module Type Safety