frontend-react-router-best-practices

What this skill does

# 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.

```tsx
// 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.

```tsx
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.

```tsx
// 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.

```tsx
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.

```tsx
// 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.

```tsx
// 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.

```ts
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.

```ts
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.

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

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

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

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

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

Deduplicate request-scoped API/DB calls.

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

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

Add request IDs for logging/correlation.

```ts
let requestId = getRequestID();
```

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

Log requests consistently with built-in middleware.

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

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

Add Server-Timing measurements to responses.

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

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

Create per-request singletons for caches.

```ts
let cache = getSingleton(context);
```

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

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

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

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

Add honeypot inputs for public forms.

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

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

Apply CORS headers to API routes.

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

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

Sanitize user-driven redirects.

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

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

Validate cookie payloads with schemas.

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

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

Extract client IP from trusted proxy headers.

```ts
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).

```tsx
// 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.

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

// com