Sign in

flagon-io/g1t

public

g1t/apps/web/.agents/skills/react-router/references/framework-mode.md

213 lines7,271 bytesCodeBlame
1# Framework Mode
2
3Framework Mode is React Router's full-stack mode. It uses the React Router Vite plugin, route config in `app/routes.ts`, route modules, generated route types, and rendering strategies such as SSR, SPA mode, and pre-rendering.
4
5Use this reference after the main skill identifies a Framework Mode app.
6
7## Read the Local Docs by Mode
8
9Start with:
10
11```txt
12react-router/docs/start/modes.md
13react-router/docs/start/framework/index.md
14```
15
16Then use the Framework docs under:
17
18```txt
19react-router/docs/start/framework/
20```
21
22Those files cover installation, routing, route modules, data loading, actions, navigation, pending UI, rendering, deploying, and testing. For task-specific details, read relevant files in:
23
24```txt
25react-router/docs/how-to/
26react-router/docs/explanation/
27```
28
29Always check the `[MODES: framework, ...]` marker in a doc before applying it.
30
31## Framework Shape
32
33Examples usually assume the default `appDirectory` of `app`. Check `react-router.config.ts` before assuming exact paths.
34
35Look for these files and conventions:
36
37```txt
38react-router.config.ts
39app/root.tsx
40app/routes.ts
41app/routes/**/*.tsx
42route modules importing from ./+types/...
43```
44
45Typical route module:
46
47```tsx
48import type { Route } from "./+types/product";
49
50export async function loader({ params }: Route.LoaderArgs) {
51 return { product: await getProduct(params.productId) };
52}
53
54export default function Product({ loaderData }: Route.ComponentProps) {
55 return <h1>{loaderData.product.name}</h1>;
56}
57```
58
59## Route Configuration
60
61Framework apps use `app/routes.ts`. Many apps use file-system routing via `flatRoutes()`, but manual route config is also supported.
62
63Before editing routes, read:
64
65```txt
66react-router/docs/start/framework/routing.md
67```
68
69If the app uses file-route conventions, read:
70
71```txt
72react-router/docs/how-to/file-route-conventions.md
73```
74
75## Route Modules
76
77Route modules are the main unit of Framework Mode. Before adding or changing route exports, read:
78
79```txt
80react-router/docs/start/framework/route-module.md
81```
82
83Common exports include:
84
85| Export | Use |
86| --------------------------------- | ------------------------------------------------------------------- |
87| `default` | Route component rendered for the match |
88| `loader` | Server data loading for SSR/pre-rendering/server data requests |
89| `clientLoader` | Browser-only data loading or supplementing server loader data |
90| `action` | Server mutation called by `<Form>`, `useSubmit`, or fetchers |
91| `clientAction` | Browser-only mutation or client-side wrapper around a server action |
92| `ErrorBoundary` | UI for errors thrown by this route's loaders/actions/component |
93| `HydrateFallback` | Initial fallback while client loader hydration runs |
94| `links` / `meta` | Route document links and metadata |
95| `handle` | Arbitrary route metadata consumed via `useMatches` |
96| `shouldRevalidate` | Overrides default loader revalidation behavior |
97| `middleware` / `clientMiddleware` | Server/client request pipeline hooks when enabled |
98
99Use generated `Route.*` types from `./+types/<route>` for route module args and props.
100
101## Layout and Root Route Rules
102
103- `app/root.tsx` is the root route and should contain global document/app shell concerns.
104- Put global providers, app-wide nav, app-wide footer, scripts/meta/links, and document structure in `root.tsx` when appropriate.
105- Use nested routes/layout routes for section-specific layouts.
106- Do not flatten routes that should share UI or data boundaries.
107
108Useful docs:
109
110```txt
111react-router/docs/explanation/special-files.md
112react-router/docs/start/framework/routing.md
113```
114
115## Data and Mutations
116
117Before working on route data:
118
119```txt
120react-router/docs/start/framework/data-loading.md
121react-router/docs/start/framework/actions.md
122```
123
124Framework rules:
125
126- Load route data with `loader` or `clientLoader`.
127- Mutate route data with `action` or `clientAction`.
128- Prefer route loaders/actions over ad hoc `useEffect` fetching for route data.
129- Use `data()`/Responses and redirects according to the docs.
130- Let React Router revalidate after actions unless the docs point you to `shouldRevalidate`.
131- In SSR/server data routes, keep Node-only/database code in server-only modules and call it from `loader`/`action`, not from browser-rendered component code.
132
133Common patterns:
134
135- Validation failure from an action: return `data({ errors, values }, { status: 400 })`, then render errors from `Route.ComponentProps["actionData"]` or `fetcher.data`.
136- Missing record in a loader: throw `data("Not Found", { status: 404 })` and render the route `ErrorBoundary`.
137- Search/filter data: parse the route request URL/search params in the loader so the URL is shareable and bookmarkable.
138
139## Forms, Fetchers, and Pending UI
140
141For forms and pending UI, read:
142
143```txt
144react-router/docs/start/framework/actions.md
145react-router/docs/start/framework/pending-ui.md
146react-router/docs/how-to/fetchers.md
147react-router/docs/explanation/form-vs-fetcher.md
148```
149
150Rules of thumb:
151
152- Search/filter form that updates the URL: `<Form method="get">`.
153- Mutation that should change URL/history or redirect after completion: `<Form method="post">`.
154- Mutation that should keep the user on the same page: `useFetcher` / `<fetcher.Form>`.
155- Optimistic UI: derive from `fetcher.formData` or `navigation.formData`.
156
157## Type Safety
158
159Before changing generated route types or typed URL behavior, read:
160
161```txt
162react-router/docs/how-to/route-module-type-safety.md
163react-router/docs/explanation/type-safety.md
164```
165
166Rules:
167
168- Import types from `./+types/<route>`.
169- Use `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ComponentProps`, etc.
170- Use type-only imports where appropriate.
171- Do not edit generated `.react-router/types` files.
172
173## Metadata
174
175Before changing `meta`, read:
176
177```txt
178react-router/docs/how-to/meta.md
179react-router/docs/start/framework/route-module.md
180```
181
182Important: `meta` receives `loaderData`; do not use deprecated `data` args.
183
184## Rendering Strategy
185
186Framework Mode can be SSR, SPA, pre-rendered, or mixed depending on config and route behavior. Before changing rendering behavior, read:
187
188```txt
189react-router/docs/start/framework/rendering.md
190react-router/docs/how-to/spa.md
191react-router/docs/how-to/pre-rendering.md
192react-router/docs/explanation/hydration.md
193```
194
195## Middleware, Sessions, and Auth
196
197Before implementing middleware or auth/session flows, read:
198
199```txt
200react-router/docs/how-to/middleware.md
201react-router/docs/explanation/sessions-and-cookies.md
202```
203
204Middleware and context APIs are version/config sensitive. Check the installed React Router version and the app's `react-router.config.ts` before implementing.
205
206## RSC Framework
207
208If this Framework app uses `unstable_reactRouterRSC` or `@vitejs/plugin-rsc`, also read:
209
210```txt
211references/rsc.md
212react-router/docs/how-to/react-server-components.md
213```