React Router performance and architecture patterns. Use when writing loaders, actions, forms, routes, or working with React Router data fetching. Triggers on tasks involving React Router routes, data loading, form handling, or route organization.

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. loader parallel fetch @rules/loader parallel fetch.md Use Promise.all for parallel data fetching in loaders. 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. loader revalidation patterns @rules/loader revalidation patterns.md Use useRevalidator for polling, focus, and reconnect revalidation. loader typing @rules/loader typing.md Use proper TypeScript typing with Route.LoaderArgs. loader url validation @rules/loader url validation.md Validate URL params with zod or invariant. loader action abort signal @rules/loader action abort signal.md Abort async work when the request is canceled. loader colocate queries @rules/loader colocate queries.md Keep data queries in colocated queries.server.ts files. route auth middleware @rules/route auth middleware.md Authenticate via middleware and authorize in each loader/action. Middleware & Security (HIGH) middleware session @rules/middleware session.md Keep a single session instance per request. middleware context storage @rules/middleware context storage.md Store context/request in AsyncLocalStorage for arg less helpers. middleware batcher @rules/middleware batcher.md Deduplicate request scoped API/DB calls. middleware request id @rules/middleware request id.md Add request IDs for logging/correlation. middleware logger @rules/middleware logger.md Log requests consistently with built in middleware. middleware server timing @rules/middleware server timing.md Add Server Timing measurements to responses. middleware singleton @rules/middleware singleton.md Create per request singletons for caches. sec fetch guards @rules/sec fetch guards.md Reject cross site mutation requests via Sec Fetch headers. form honeypot @rules/form honeypot.md Add honeypot inputs for public forms. cors headers @rules/cors headers.md Apply CORS headers to API routes. safe redirects @rules/safe redirects.md Sanitize user driven redirects. typed cookies @rules/typed cookies.md Validate cookie payloads with schemas. client ip address @rules/client ip address.md Extract client IP from trusted proxy headers. 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). data only route calls hooks @rules/data only route calls hooks.md Only route components call useLoaderData / useActionData . Children receive props. Actions & Forms (CRITICAL) action validation @rules/action validation.md Validate form data with zod schemas. action error handling @rules/action error handling.md Return validation errors, don't throw. Re throw redirects and unknown errors. action redirect after @rules/action redirect after.md Redirect after successful mutations to prevent resubmission. action zod transform @rules/action zod transform.md Use Zod .transform() for input sanitization during validation. action client validation @rules/action client validation.md Use clientAction for instant client side validation before hitting the server. Form Patterns (MEDIUM) form fetcher vs form @rules/form fetcher vs form.md Use useFetcher for non navigation mutations, Form for navigation. form pending state @rules/form pending state.md Show loading states with useNavigation or fetcher.state. form reset on success @rules/form reset on success.md Reset uncontrolled form inputs after successful submission. form persist on error @rules/form persist on error.md Return field values from actions on validation errors to repopulate inputs. Client Functions (MEDIUM) clientloader debounce @rules/clientloader debounce.md Use clientLoader/clientAction to debounce at the route level. Migrations (HIGH) migrate defer to data @rules/migrate defer to data.md Migrate from defer() to data() with promises for Single Fetch. Streaming (CRITICAL) streaming await suspense @rules/streaming await suspense.md Use Await with Suspense for streamed data. migrate jsonhash to native @rules/migrate jsonhash to native.md Stop using jsonHash, use native Promise.all or data() patterns. migrate json to data @rules/migrate json to data.md Migrate from deprecated json() to data(). migrate namedaction to intent @rules/migrate namedaction to intent.md Migrate from namedAction helper to z.discriminatedUnion pattern. Error Handling (MEDIUM) error boundary layout @rules/error boundary layout.md Implement layout aware ErrorBoundary with useRouteError. error boundary route @rules/error boundary route.md Add ErrorBoundary to routes with data fetching to catch loader/action errors. Navigation & Linking (MEDIUM) link prefetch intent @rules/link prefetch intent.md Use prefetch="intent" for faster navigation on hover/focus. navigation avoid navigate back @rules/navigation avoid navigate back.md Avoid navigate( 1) for in app back links. prefetch fetcher data @rules/prefetch fetcher data.md Use PrefetchPageLinks to preload data for fetcher.load() calls. Resource Routes & Responses (MEDIUM) response helpers @rules/response helpers.md Use response helpers for resource routes. sse event stream @rules/sse event stream.md Stream updates with eventStream and useEventSource . prefetch cache @rules/prefetch cache.md Use short caching for prefetch requests. Route Organization (MEDIUM) route organization @rules/route organization.md Use folder routes with colocated files. route resource routes @rules/route resource routes.md Use resource routes for API like endpoints without UI. route action routes @rules/route action routes.md Centralize reusable actions in dedicated resource routes using actions.noun verb.ts naming. route should revalidate @rules/route should revalidate.md Optimize revalidation with shouldRevalidate. route handle metadata @rules/route handle metadata.md Use handle export with app defined handle types for route metadata. Meta & SEO (MEDIUM) meta function v2 @rules/meta function v2.md Use meta function with loader data for dynamic SEO. Route Conventions (MEDIUM) route component naming @rules/route component naming.md Name the default export Component in route files. route import restrictions @rules/route import restrictions.md Avoid importing from other route files. Routes import shared modules, not each other.

frontend-react-router-best-practices