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)