Frontend React Router Best Practices

React Router Best Practices

Performance optimization and architecture patterns for React Router applications. Contains 55 rules across 11 categories focused on data loading, actions, forms, streaming, and route organization.

When to Apply

Reference these guidelines when:

• Writing new React Router routes (loaders, actions)
• Handling forms and mutations
• Implementing streaming with Single Fetch
• Organizing route files and colocating queries
• Setting up authentication patterns
• Adding SEO/meta tags

Rules Summary

Data Loading (CRITICAL)

loader-avoid-waterfalls - @rules/loader-avoid-waterfalls.md

All data fetching happens in loaders. Never fetch in components with useEffect.

// BAD: fetching in component
function Profile() {
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch("/api/user")
      .then((r) => r.json())
      .then(setUser);
  }, []);
  if (!user) return <Spinner />;
  return <div>{user.name}</div>;
}

// GOOD: fetch in loader
export async function loader({ request }: Route.LoaderArgs) {
  let user = await getUser(request);
  return data({ user });
}

export default function Component() {
  const { user } = useLoaderData<typeof loader>();
  return <div>{user.name}</div>;
}

loader-parallel-fetch - @rules/loader-parallel-fetch.md

Use Promise.all for parallel data fetching in loaders.

import { data } from "react-router";

// Bad: sequential fetches (slow)
export async function loader({ request }: Route.LoaderArgs) {
  let user = await getUser(request);
  let posts = await getPosts(user.id);
  let comments = await getComments(user.id);
  return data({ user, posts, comments });
}

// Good: parallel fetches
export async function loader({ request }: Route.LoaderArgs) {
  let user = await getUser(request);
  let [posts, comments] = await Promise.all([
    getPosts(user.id),
    getComments(user.id),
  ]);
  return data({ user, posts, comments });
}

loader-request-caching - @rules/loader-request-caching.md

API clients dedupe calls within the same request via context. Fetch in each loader that needs data.

// Both loaders can call getUser - cached per request
export async function loader({ request, context }: Route.LoaderArgs) {
  let client = await authenticate(request, context);
  let user = await getUser(client); // Uses cached result if already fetched
  return data({ user });
}

loader-revalidation-patterns - @rules/loader-revalidation-patterns.md

Use useRevalidator for polling, focus, and reconnect revalidation.

const { revalidate } = useRevalidator();

useEffect(() => {
  if (visibilityState === "hidden") return; // Don't poll hidden tabs
  let id = setInterval(revalidate, 30000);
  return () => clearInterval(id);
}, [revalidate, visibilityState]);

loader-typing - @rules/loader-typing.md

Use proper TypeScript typing with Route.LoaderArgs.

// Good: typed loader with useLoaderData
import { data } from "react-router";
import { useLoaderData } from "react-router";

export async function loader({ request, params }: Route.LoaderArgs) {
  return data({ user: await getUser(params.id) });
}

export default function Component() {
  const { user } = useLoaderData<typeof loader>();
  return <div>{user.name}</div>;
}

loader-url-validation - @rules/loader-url-validation.md

Validate URL params with zod or invariant.

// Good: validate params early
import { data } from "react-router";
import { z } from "zod";

export async function loader({ params }: Route.LoaderArgs) {
  let itemId = z.string().parse(params.itemId);
  return data({ item: await getItem(itemId) });
}

loader-action-abort-signal - @rules/loader-action-abort-signal.md

Abort async work when the request is canceled.

export async function loader({ request }: Route.LoaderArgs) {
  let response = await fetch(url, { signal: request.signal });
  return data(await response.json());
}

loader-colocate-queries - @rules/loader-colocate-queries.md

Keep data queries in colocated queries.server.ts files.

routes/
  _.projects/
    queries.server.ts  # All data fetching functions
    route.tsx          # Loader calls query functions
    components/        # Route-specific components

route-auth-middleware - @rules/route-auth-middleware.md

Authenticate via middleware and authorize in each loader/action.

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

export async function loader({ context }: Route.LoaderArgs) {
  authorize(context, { requireUser: true, onboardingComplete: true });
  return null;
}

Middleware & Security (HIGH)

middleware-session - @rules/middleware-session.md

Keep a single session instance per request.

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

middleware-context-storage - @rules/middleware-context-storage.md

Store context/request in AsyncLocalStorage for arg-less helpers.

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

middleware-batcher - @rules/middleware-batcher.md

Deduplicate request-scoped API/DB calls.

let result = await getBatcher().batch("key", () => getData());

middleware-request-id - @rules/middleware-request-id.md

Add request IDs for logging/correlation.

let requestId = getRequestID();

middleware-logger - @rules/middleware-logger.md

Log requests consistently with built-in middleware.

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

middleware-server-timing - @rules/middleware-server-timing.md

Add Server-Timing measurements to responses.

return getTimingCollector().measure("load", "Load data", () => getData());

middleware-singleton - @rules/middleware-singleton.md

Create per-request singletons for caches.

let cache = getSingleton(context);

sec-fetch-guards - @rules/sec-fetch-guards.md

Reject cross-site mutation requests via Sec-Fetch headers.

if (fetchSite(request) === "cross-site") throw new Response(null, { status: 403 });

form-honeypot - @rules/form-honeypot.md

Add honeypot inputs for public forms.

<Form method="post">
  <HoneypotInputs />
</Form>

cors-headers - @rules/cors-headers.md

Apply CORS headers to API routes.

return await cors(request, data(await getData()));

safe-redirects - @rules/safe-redirects.md

Sanitize user-driven redirects.

return redirect(safeRedirect(redirectTo, "/"));

typed-cookies - @rules/typed-cookies.md

Validate cookie payloads with schemas.

let typed = createTypedCookie({ cookie, schema });

client-ip-address - @rules/client-ip-address.md

Extract client IP from trusted proxy headers.

let ip = getClientIPAddress(request);

data-parent-route-data - @rules/data-parent-route-data.md

Use useRouteLoaderData for UI-only access to parent data. For loader logic, fetch in each loader (API clients cache per request).

// UI-only access - use useRouteLoaderData
export default function ChildRoute() {
  const { user } = useRouteLoaderData<typeof profileLoader>("routes/_layout");
  return <div>Welcome, {user.name}</div>;
}

// Loader needs data - fetch again (cached, no extra request)
export async function loader({ request }: Route.LoaderArgs) {
  let client = await authenticate(request);
  let user = await getUser(client); // Uses cached result
  let settings = await getSettings(client, user.id);
  return data({ settings });
}

data-only-route-calls-hooks - @rules/data-only-route-calls-hooks.md

Only route components call useLoaderData/useActionData. Children receive props.

// route.tsx - only place that calls useLoaderData
export default function ItemsRoute() {
  const { items } = useLoaderData<typeof loader>();
  return <ItemList items={items} />;
}