--- name: react-router-framework-mode description: Build full-stack React applications using React Router's framework mode. Use when configuring routes, working with loaders and actions, handling forms, handling navigation, pending\/optimistic UI, error boundaries, or working with react-router.config.ts or other react router conventions. license: MIT --- # 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 ``, ``, `

`, `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: | Reference | Use When | | ------------------------------------ | ----------------------------------------------------- | | `references\/routing.md` | Configuring routes, nested routes, dynamic segments | | `references\/route-modules.md` | Understanding all route module exports | | `references\/special-files.md` | Customizing root.tsx, adding global nav\/footer, fonts | | `references\/data-loading.md` | Loading data with loaders, streaming, caching | | `references\/actions.md` | Handling forms, mutations, validation | | `references\/navigation.md` | Links, programmatic navigation, redirects | | `references\/pending-ui.md` | Loading states, optimistic UI | | `references\/error-handling.md` | Error boundaries, error reporting | | `references\/rendering-strategies.md` | SSR vs SPA vs pre-rendering configuration | | `references\/middleware.md` | Adding middleware (requires v7.9.0+) | | `references\/sessions.md` | Cookie sessions, authentication, protected routes | | `references\/type-safety.md` | Auto-generated route types, type imports, type safety | ## Version Compatibility Some features require specific React Router versions. **Always verify before implementing:** ```bash npm list react-router ``` | Feature | Minimum Version | Notes | | ----------------------- | --------------- | ----------------------------- | | Middleware | 7.9.0+ | Requires `v8_middleware` flag | | Core framework features | 7.0.0+ | loaders, actions, Form, etc. | ## Critical Patterns These are the most important patterns to follow. Load the relevant reference for full details. ### Forms & Mutations **Search forms** - use ``, NOT `onSubmit` with `setSearchParams`: ```tsx \/\/ ✅ Correct <\/Form> \/\/ ❌ Wrong - don't manually handle search params { e.preventDefault(); setSearchParams(...) }}> ``` **Inline mutations** - use `useFetcher`, NOT `` (which causes page navigation): ```tsx const fetcher = useFetcher(); const optimistic = fetcher.formData?.get("favorite") === "true" ?? isFavorite;