[pull] main from remix-run:main

.agents/skills/react-router/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: react-router
+description: Build applications with React Router in Framework, Data, Declarative, and unstable RSC modes. Use when configuring routes, route modules, loaders, actions, forms, fetchers, navigation, pending UI, SSR/SPA/pre-rendering, middleware, URL params/search params, or React Router upgrades.
+license: MIT
+---
+
+# React Router
+
+React Router is mode-specific. Before changing an app, identify the mode, load the matching reference, then read the installed docs for the installed package version.
+
+## Identify the Mode
+
+Do not apply Framework/Data patterns to a Declarative app unless you are intentionally migrating modes.
+
+### Framework Mode
+
+Use Framework Mode guidance when you see:
+
+- `@react-router/dev` in dependencies
+- `react-router.config.ts`
+- `app/routes.ts`
+- `app/entry.server.tsx` and/or `app/entry.client.tsx` files
+- route modules under `app/routes/`
+- route exports like `loader`, `action`, `clientLoader`, `clientAction`, `ErrorBoundary`, `meta`, `links`, or `headers`
+- imports from `./+types/...`
+- the React Router Vite plugin from `@react-router/dev/vite`
+
+Framework examples usually use the default `app/` directory, but check `react-router.config.ts` for a custom `appDirectory` before assuming exact paths.
+
+Then read `references/framework-mode.md`.
+
+### Data Mode
+
+Use Data Mode guidance when you see:
+
+- `createBrowserRouter`, `createHashRouter`, `createMemoryRouter`, or `createStaticRouter`
+- `<RouterProvider router={router}>`
+- route objects with properties like `path`, `children`, `loader`, `action`, `Component`, `ErrorBoundary`, or `lazy`
+- data APIs without the Framework Vite plugin
+
+Then read `references/data-mode.md`.
+
+### Declarative Mode
+
+Use Declarative Mode guidance when you see:
+
+- `<BrowserRouter>`, `<HashRouter>`, or `<MemoryRouter>`
+- `<Routes>` and `<Route>` JSX route configuration
+- route components passed with `element={<Component />}`
+- no data router, no route module convention, and no loaders/actions
+
+Then read `references/declarative-mode.md`.
+
+### RSC Framework and RSC Data Modes
+
+React Server Components support is unstable and exists in both Framework and Data variants. Use RSC guidance when you see:
+
+- `unstable_reactRouterRSC`
+- `@vitejs/plugin-rsc`
+- `unstable_RSCRouteConfig`
+- RSC entry files such as `entry.rsc`
+- `ServerComponent`, `ServerErrorBoundary`, `ServerLayout`, or `ServerHydrateFallback`
+- React directives or boundary packages such as `"use client"`, `"server-only"`, or `"client-only"`
+
+For RSC Framework, read both `references/framework-mode.md` and `references/rsc.md`.
+For RSC Data, read both `references/data-mode.md` and `references/rsc.md`.
+
+## Use Installed Docs as Source of Truth
+
+React Router ships markdown docs in the package so guidance can match the installed version:
+
+```txt
+node_modules/react-router/docs/
+```
+
+Key docs paths:
+
+```txt
+node_modules/react-router/docs/index.md
+node_modules/react-router/docs/start/
+node_modules/react-router/docs/how-to/
+node_modules/react-router/docs/explanation/
+node_modules/react-router/docs/upgrading/
+```
+
+When this skill references `react-router/docs/...`, read the matching file under `node_modules/react-router/docs/`. If the installed version does not include local docs, use the repo `docs/` directory when working inside the React Router repository; in a consuming app, fall back to version-matched website docs.
+
+Most docs include a mode marker near the top:
+
+```txt
+[MODES: framework, data, declarative]
+```
+
+Only apply a doc when its mode marker matches the app mode. If a task spans modes, prefer the section or file that matches the current app.
+
+RSC is documented primarily in:
+
+```txt
+node_modules/react-router/docs/how-to/react-server-components.md
+```
+
+## Skill References
+
+Load the relevant reference after identifying the mode:
+
+| Reference                        | Use When                                      |
+| -------------------------------- | --------------------------------------------- |
+| `references/framework-mode.md`   | Framework Mode or RSC Framework base behavior |
+| `references/data-mode.md`        | Data Mode or RSC Data base behavior           |
+| `references/declarative-mode.md` | Declarative Mode                              |
+| `references/rsc.md`              | Any unstable RSC app                          |
+
+## Mode Migration Doc Index
+
+If the user explicitly asks to switch modes, read the target mode reference plus the migration-relevant docs:
+
+| Migration                            | Docs to read                                                                                                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Declarative → Data                   | `react-router/docs/start/modes.md`, `react-router/docs/start/data/routing.md`, `react-router/docs/start/data/data-loading.md`, `react-router/docs/start/data/actions.md`                                                              |
+| Declarative/Data → Framework         | `react-router/docs/start/modes.md`, `react-router/docs/start/framework/routing.md`, `react-router/docs/start/framework/route-module.md`, `react-router/docs/how-to/route-module-type-safety.md`                                       |
+| Framework SPA/SSR/pre-render changes | `react-router/docs/start/framework/rendering.md`, `react-router/docs/how-to/spa.md`, `react-router/docs/how-to/pre-rendering.md`, `react-router/docs/start/framework/data-loading.md`, `react-router/docs/start/framework/actions.md` |
+| Future flags/upgrades                | `react-router/docs/upgrading/future.md` and relevant files under `react-router/docs/upgrading/`                                                                                                                                       |

.agents/skills/react-router/references/data-mode.md

@@ -0,0 +1,165 @@
+# Data Mode
+
+Data Mode uses data routers such as `createBrowserRouter` and renders with `<RouterProvider>`. It gives an app route objects, loaders, actions, pending UI, fetchers, and SSR primitives without adopting the Framework Vite plugin or route-module file conventions.
+
+Use this reference after the main skill identifies a Data Mode app.
+
+## Read the Local Docs by Mode
+
+Start with:
+
+```txt
+react-router/docs/start/modes.md
+react-router/docs/start/data/index.md
+```
+
+Then use the Data docs under:
+
+```txt
+react-router/docs/start/data/
+```
+
+Those files cover installation, route objects, routing, data loading, actions, navigation, pending UI, and testing. For task-specific details, read relevant files in:
+
+```txt
+react-router/docs/how-to/
+react-router/docs/explanation/
+```
+
+Always check the `[MODES: data, ...]` marker in a doc before applying it.
+
+## Data Router Shape
+
+Typical setup:
+
+```tsx
+import { createBrowserRouter, RouterProvider } from "react-router";
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    loader: rootLoader,
+    children: [
+      { index: true, Component: Home },
+      {
+        path: "projects/:projectId",
+        Component: Project,
+        loader: projectLoader,
+      },
+    ],
+  },
+]);
+
+root.render(<RouterProvider router={router} />);
+```
+
+Look for route object arrays and APIs such as:
+
+- `createBrowserRouter`
+- `createHashRouter`
+- `createMemoryRouter`
+- `RouterProvider`
+- `loader`
+- `action`
+- `Component`
+- `ErrorBoundary`
+- `lazy`
+- `children`
+
+## Route Objects and Routing
+
+Before editing route configuration, read:
+
+```txt
+react-router/docs/start/data/routing.md
+react-router/docs/start/data/route-object.md
+```
+
+Rules:
+
+- Keep route objects outside render when possible.
+- Use nested routes for shared layouts and data boundaries.
+- Use index routes for default child content.
+- Use dynamic segments and splats according to route-object docs.
+- Prefer `Component`/`ErrorBoundary` route object properties in Data Mode examples unless the existing app uses `element` consistently.
+
+## Data and Mutations
+
+Before working on data loading or mutations, read:
+
+```txt
+react-router/docs/start/data/data-loading.md
+react-router/docs/start/data/actions.md
+```
+
+Rules:
+
+- Load route data with route `loader` functions.
+- Mutate route data with route `action` functions.
+- Prefer loaders/actions over route-level `useEffect` fetching.
+- Use `request`, `params`, and returned/throwable Responses as described in the docs.
+- Let React Router revalidate after actions unless there is a documented reason to customize revalidation.
+
+Common patterns:
+
+- Validation failure from an action: return `data({ errors, values }, { status: 400 })`, then render errors with `useActionData()` or `fetcher.data`.
+- Missing record in a loader: throw `data("Not Found", { status: 404 })` and render the route `ErrorBoundary`.
+- Search/filter data: parse `new URL(request.url).searchParams` in the loader so the URL is shareable and bookmarkable.
+
+## Forms, Fetchers, and Pending UI
+
+For forms and pending UI, read:
+
+```txt
+react-router/docs/start/data/actions.md
+react-router/docs/start/data/pending-ui.md
+react-router/docs/how-to/fetchers.md
+react-router/docs/explanation/form-vs-fetcher.md
+```
+
+Rules of thumb:
+
+- Search/filter form that updates the URL: `<Form method="get">`.
+- Mutation that should change URL/history or redirect after completion: `<Form method="post">`.
+- Mutation that should keep the user on the same page: `useFetcher` / `<fetcher.Form>`.
+- Optimistic UI: derive from `fetcher.formData` or `navigation.formData`.
+
+## Navigation and URL State
+
+Before changing navigation or search params, read:
+
+```txt
+react-router/docs/start/data/navigating.md
+react-router/docs/how-to/search-params.md
+react-router/docs/explanation/location.md
+```
+
+Rules:
+
+- Use `<Link>`/`<NavLink>` for user-initiated internal navigation.
+- Use `redirect` in loaders/actions when navigation follows data loading or mutations.
+- Use `useNavigate` for imperative client-side event navigation.
+- Treat URL params as strings and validate/parse them.
+- Preserve unrelated search params unless intentionally resetting them.
+
+## SSR in Data Mode
+
+Data Mode SSR is manual and lower-level than Framework Mode. Before implementing or changing SSR, read the Data Mode custom/SSR docs and match existing server abstractions.
+
+Start with:
+
+```txt
+react-router/docs/start/data/custom.md
+```
+
+Look for APIs like `createStaticHandler`, `createStaticRouter`, `StaticRouterProvider`, and hydration data handling in the current app before changing anything.
+
+## RSC Data
+
+If this Data Mode app uses `unstable_RSCRouteConfig`, RSC route config, or low-level RSC server APIs, also read:
+
+```txt
+references/rsc.md
+react-router/docs/how-to/react-server-components.md
+```