create-react-router 8.0.1 → 8.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # `create-react-router`
 
+## v8.2.0
+
+### Minor Changes
+
+- Detect `nub` as a supported package manager when creating new projects ([#15276](https://github.com/remix-run/react-router/pull/15276))
+
+## v8.1.0
+
+### Minor Changes
+
+- Add a default-on CLI option to include the official React Router agent skill in generated projects ([#15213](https://github.com/remix-run/react-router/pull/15213))
+  - New projects include `.agents/skills/react-router` by default when running with `--yes` or in non-interactive shells
+  - Interactive runs prompt to include the skill, defaulting to yes
+  - Use `--no-agent-skills` to skip copying the skill
+
+### Patch Changes
+
+- Use Node's built-in utilities for CLI argument parsing, ANSI-stripping, and child process execution to remove the `arg`, `strip-ansi`, and `execa` dependencies ([#15231](https://github.com/remix-run/react-router/pull/15231))
+
 ## v8.0.1
 
 ### Patch Changes

package/dist/agent-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/`                                                                                                                                       |

package/dist/agent-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
+```

package/dist/agent-skills/react-router/references/declarative-mode.md

@@ -0,0 +1,123 @@
+# Declarative Mode
+
+Declarative Mode is React Router's simplest mode. It uses router components like `<BrowserRouter>` and JSX routes with `<Routes>`/`<Route>`. It does not provide loaders, actions, fetchers, or data-router pending UI.
+
+Use this reference after the main skill identifies a Declarative Mode app.
+
+## Read the Local Docs by Mode
+
+Start with:
+
+```txt
+react-router/docs/start/modes.md
+react-router/docs/start/declarative/index.md
+```
+
+Then use the Declarative docs under:
+
+```txt
+react-router/docs/start/declarative/
+```
+
+Those files cover installation, routing, navigation, and URL values. For conceptual details, read relevant files in:
+
+```txt
+react-router/docs/explanation/
+```
+
+Always check the `[MODES: declarative, ...]` marker in a doc before applying it.
+
+## Declarative Router Shape
+
+Typical setup:
+
+```tsx
+import { BrowserRouter, Routes, Route } from "react-router";
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="about" element={<About />} />
+        <Route path="dashboard" element={<DashboardLayout />}>
+          <Route index element={<DashboardHome />} />
+          <Route path="settings" element={<Settings />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+Look for APIs such as:
+
+- `<BrowserRouter>`
+- `<HashRouter>`
+- `<MemoryRouter>`
+- `<Routes>`
+- `<Route>`
+- `element={<Component />}`
+- `useRoutes`
+
+## Routing
+
+Before editing routes, read:
+
+```txt
+react-router/docs/start/declarative/routing.md
+```
+
+Rules:
+
+- Use `<Routes>` and `<Route>` for route configuration.
+- Use nested routes with `<Outlet>` for shared layout.
+- Use index routes for default child UI.
+- Use route params and splats according to the declarative routing docs.
+- Do not add route object loaders/actions to a Declarative router.
+
+## Navigation
+
+Before changing navigation, read:
+
+```txt
+react-router/docs/start/declarative/navigating.md
+```
+
+Rules:
+
+- Use `<Link>` or `<NavLink>` for user-initiated internal navigation.
+- Use `NavLink` when active styling matters.
+- Use `useNavigate` for imperative navigation from event handlers or effects.
+- Do not use plain `<a href>` for internal navigation unless intentionally forcing a full document navigation.
+
+## URL Values
+
+Before changing params, search params, or location state, read:
+
+```txt
+react-router/docs/start/declarative/url-values.md
+react-router/docs/explanation/location.md
+```
+
+Rules:
+
+- Use `useParams` for dynamic route params.
+- Use `useSearchParams` for query string state.
+- Use `useLocation` for the current location object and navigation state.
+- Validate and parse URL params; they are strings and can be absent.
+- Preserve unrelated search params unless intentionally resetting them.
+
+## Mode Boundary
+
+Declarative Mode does not have Data/Framework APIs such as:
+
+- `loader`
+- `action`
+- `<Form>`
+- `useFetcher`
+- `useNavigation`
+- route module exports
+- generated `./+types` route types
+
+If the user asks for route data loading, DB/API-backed data, CRUD, form mutations, validation returned from submissions, revalidation, pending UI, optimistic UI, or fetchers, recommend Data Mode or Framework Mode depending on how much structure they want. Ask before migrating unless they already requested it.

package/dist/agent-skills/react-router/references/framework-mode.md

@@ -0,0 +1,213 @@
+# Framework Mode
+
+Framework 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.
+
+Use this reference after the main skill identifies a Framework Mode app.
+
+## Read the Local Docs by Mode
+
+Start with:
+
+```txt
+react-router/docs/start/modes.md
+react-router/docs/start/framework/index.md
+```
+
+Then use the Framework docs under:
+
+```txt
+react-router/docs/start/framework/
+```
+
+Those files cover installation, routing, route modules, data loading, actions, navigation, pending UI, rendering, deploying, and testing. For task-specific details, read relevant files in:
+
+```txt
+react-router/docs/how-to/
+react-router/docs/explanation/
+```
+
+Always check the `[MODES: framework, ...]` marker in a doc before applying it.
+
+## Framework Shape
+
+Examples usually assume the default `appDirectory` of `app`. Check `react-router.config.ts` before assuming exact paths.
+
+Look for these files and conventions:
+
+```txt
+react-router.config.ts
+app/root.tsx
+app/routes.ts
+app/routes/**/*.tsx
+route modules importing from ./+types/...
+```
+
+Typical route module:
+
+```tsx
+import type { Route } from "./+types/product";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  return { product: await getProduct(params.productId) };
+}
+
+export default function Product({ loaderData }: Route.ComponentProps) {
+  return <h1>{loaderData.product.name}</h1>;
+}
+```
+
+## Route Configuration
+
+Framework apps use `app/routes.ts`. Many apps use file-system routing via `flatRoutes()`, but manual route config is also supported.
+
+Before editing routes, read:
+
+```txt
+react-router/docs/start/framework/routing.md
+```
+
+If the app uses file-route conventions, read:
+
+```txt
+react-router/docs/how-to/file-route-conventions.md
+```
+
+## Route Modules
+
+Route modules are the main unit of Framework Mode. Before adding or changing route exports, read:
+
+```txt
+react-router/docs/start/framework/route-module.md
+```
+
+Common exports include:
+
+| Export                            | Use                                                                 |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `default`                         | Route component rendered for the match                              |
+| `loader`                          | Server data loading for SSR/pre-rendering/server data requests      |
+| `clientLoader`                    | Browser-only data loading or supplementing server loader data       |
+| `action`                          | Server mutation called by `<Form>`, `useSubmit`, or fetchers        |
+| `clientAction`                    | Browser-only mutation or client-side wrapper around a server action |
+| `ErrorBoundary`                   | UI for errors thrown by this route's loaders/actions/component      |
+| `HydrateFallback`                 | Initial fallback while client loader hydration runs                 |
+| `links` / `meta`                  | Route document links and metadata                                   |
+| `handle`                          | Arbitrary route metadata consumed via `useMatches`                  |
+| `shouldRevalidate`                | Overrides default loader revalidation behavior                      |
+| `middleware` / `clientMiddleware` | Server/client request pipeline hooks when enabled                   |
+
+Use generated `Route.*` types from `./+types/<route>` for route module args and props.
+
+## Layout and Root Route Rules
+
+- `app/root.tsx` is the root route and should contain global document/app shell concerns.
+- Put global providers, app-wide nav, app-wide footer, scripts/meta/links, and document structure in `root.tsx` when appropriate.
+- Use nested routes/layout routes for section-specific layouts.
+- Do not flatten routes that should share UI or data boundaries.
+
+Useful docs:
+
+```txt
+react-router/docs/explanation/special-files.md
+react-router/docs/start/framework/routing.md
+```
+
+## Data and Mutations
+
+Before working on route data:
+
+```txt
+react-router/docs/start/framework/data-loading.md
+react-router/docs/start/framework/actions.md
+```
+
+Framework rules:
+
+- Load route data with `loader` or `clientLoader`.
+- Mutate route data with `action` or `clientAction`.
+- Prefer route loaders/actions over ad hoc `useEffect` fetching for route data.
+- Use `data()`/Responses and redirects according to the docs.
+- Let React Router revalidate after actions unless the docs point you to `shouldRevalidate`.
+- 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.
+
+Common patterns:
+
+- Validation failure from an action: return `data({ errors, values }, { status: 400 })`, then render errors from `Route.ComponentProps["actionData"]` or `fetcher.data`.
+- Missing record in a loader: throw `data("Not Found", { status: 404 })` and render the route `ErrorBoundary`.
+- Search/filter data: parse the route request URL/search params 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/framework/actions.md
+react-router/docs/start/framework/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`.
+
+## Type Safety
+
+Before changing generated route types or typed URL behavior, read:
+
+```txt
+react-router/docs/how-to/route-module-type-safety.md
+react-router/docs/explanation/type-safety.md
+```
+
+Rules:
+
+- Import types from `./+types/<route>`.
+- Use `Route.LoaderArgs`, `Route.ActionArgs`, `Route.ComponentProps`, etc.
+- Use type-only imports where appropriate.
+- Do not edit generated `.react-router/types` files.
+
+## Metadata
+
+Before changing `meta`, read:
+
+```txt
+react-router/docs/how-to/meta.md
+react-router/docs/start/framework/route-module.md
+```
+
+Important: `meta` receives `loaderData`; do not use deprecated `data` args.
+
+## Rendering Strategy
+
+Framework Mode can be SSR, SPA, pre-rendered, or mixed depending on config and route behavior. Before changing rendering behavior, read:
+
+```txt
+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/explanation/hydration.md
+```
+
+## Middleware, Sessions, and Auth
+
+Before implementing middleware or auth/session flows, read:
+
+```txt
+react-router/docs/how-to/middleware.md
+react-router/docs/explanation/sessions-and-cookies.md
+```
+
+Middleware and context APIs are version/config sensitive. Check the installed React Router version and the app's `react-router.config.ts` before implementing.
+
+## RSC Framework
+
+If this Framework app uses `unstable_reactRouterRSC` or `@vitejs/plugin-rsc`, also read:
+
+```txt
+references/rsc.md
+react-router/docs/how-to/react-server-components.md
+```

package/dist/agent-skills/react-router/references/rsc.md

@@ -0,0 +1,90 @@
+# React Server Components (RSC)
+
+React Router's RSC support is unstable and exists in two variants:
+
+- **RSC Framework Mode**: Framework Mode with the unstable RSC Vite plugin.
+- **RSC Data Mode**: lower-level RSC runtime APIs and manual bundler/server integration.
+
+Use this reference in addition to `framework-mode.md` or `data-mode.md` after the main skill identifies an RSC app.
+
+## Read the Local RSC Docs
+
+Start with:
+
+```txt
+react-router/docs/how-to/react-server-components.md
+```
+
+Then read the relevant base mode docs:
+
+```txt
+react-router/docs/start/framework/
+react-router/docs/start/data/
+```
+
+RSC docs may describe differences from non-RSC mode rather than repeating every Framework/Data concept, so keep both layers in mind.
+
+## Detect RSC Framework Mode
+
+Look for:
+
+- `unstable_reactRouterRSC` imported from `@react-router/dev/vite`
+- `@vitejs/plugin-rsc`
+- `vite.config.ts` with `plugins: [reactRouterRSC(), rsc()]`
+- Framework route modules plus RSC route exports
+- RSC entry files such as `entry.rsc`
+
+RSC Framework Mode uses a different Vite plugin from non-RSC Framework Mode. Do not swap it for the regular `reactRouter()` plugin.
+
+## Detect RSC Data Mode
+
+Look for:
+
+- `unstable_RSCRouteConfig`
+- route config passed to lower-level RSC APIs
+- APIs such as `unstable_matchRSCServerRequest`, `unstable_routeRSCServerRequest`, `unstable_RSCHydratedRouter`, or `unstable_RSCStaticRouter`
+- custom bundler/server setup around RSC
+
+RSC Data Mode is more manual than RSC Framework Mode. Match the app's bundler and server abstractions before changing routes or entries.
+
+## RSC Route Module Differences
+
+In RSC Framework Mode, many normal Framework Mode concepts still apply, but routes can use server component exports.
+
+Important route-module concepts from the RSC docs include:
+
+- `ServerComponent` instead of the usual client `default` component
+- `ServerErrorBoundary` paired with `ErrorBoundary`
+- `ServerLayout` paired with `Layout`
+- `ServerHydrateFallback` paired with `HydrateFallback`
+- server-rendered React elements returned from loaders/actions
+
+A route module cannot export both the normal client component and its server component counterpart for the same role. Read the RSC docs before adding these exports.
+
+## Client/Server Boundaries
+
+RSC code must respect React's client/server split:
+
+- Use `"use client"` for components that need hooks, browser APIs, or event handlers.
+- Use server-only modules for server data access and secrets.
+- In RSC Framework Mode, prefer the `server-only` and `client-only` boundary imports described in the docs.
+- Do not assume `.server`/`.client` file naming works the same way in RSC Framework Mode; read the RSC docs before relying on those conventions.
+
+## Data Loading in RSC
+
+RSC changes where data can be loaded:
+
+- Server Components can fetch data directly on the server.
+- Loaders/actions may still exist and can have RSC-specific behavior.
+- Client components still need client-safe data and cannot directly access server-only modules.
+
+When choosing between a server component fetch, a loader, and a client loader/action, follow the RSC docs and match existing app patterns.
+
+## Stability
+
+RSC APIs are explicitly unstable. Before implementing or refactoring RSC code:
+
+- Check the installed React Router version.
+- Check the installed `@vitejs/plugin-rsc` version.
+- Read the app's existing RSC entry/config files.
+- Prefer minimal changes that match current patterns.

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * create-react-router v8.0.1
+ * create-react-router v8.2.0
  *
  * Copyright (c) Remix Software Inc.
  *
@@ -10,22 +10,20 @@
  * @license MIT
  */
 import process from "node:process";
+import { spawn } from "node:child_process";
 import fs, { existsSync } from "node:fs";
 import { cp, readFile, readdir, realpath, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import stripAnsi from "strip-ansi";
-import { execa } from "execa";
-import arg from "arg";
+import url, { fileURLToPath } from "node:url";
+import { parseArgs, promisify, stripVTControlCharacters } from "node:util";
 import * as semver from "semver";
 import sortPackageJSON from "sort-package-json";
 import { beep, cursor, erase } from "sisteransi";
 import EventEmitter from "node:events";
 import readline from "node:readline";
 import pc from "picocolors";
-import url from "node:url";
 import stream from "node:stream";
-import { promisify } from "node:util";
 import gunzip from "gunzip-maybe";
 import tar from "tar-fs";
 //#region utils.ts
@@ -1239,9 +1237,12 @@ var CopyTemplateError = class extends Error {
 };
 //#endregion
 //#region package.json
-var version = "8.0.1";
+var version = "8.2.0";
 //#endregion
 //#region index.ts
+const currentFileDir = path.dirname(fileURLToPath(import.meta.url));
+const packageDir = path.basename(currentFileDir) === "dist" ? path.dirname(currentFileDir) : currentFileDir;
+const agentSkillPath = path.join(packageDir, "dist/agent-skills/react-router");
 async function createReactRouter(argv) {
 	let ctx = await getContext(argv);
 	if (ctx.help) {
@@ -1259,6 +1260,8 @@ async function createReactRouter(argv) {
 		copyTempDirToAppDirStep,
 		gitInitQuestionStep,
 		installDependenciesQuestionStep,
+		agentSkillsQuestionStep,
+		copyAgentSkillsToAppDirStep,
 		installDependenciesStep,
 		gitInitStep,
 		doneStep
@@ -1271,33 +1274,48 @@ async function createReactRouter(argv) {
 	}
 }
 async function getContext(argv) {
-	let flags = arg({
-		"--debug": Boolean,
-		"--react-router-version": String,
-		"-v": "--react-router-version",
-		"--template": String,
-		"--token": String,
-		"--yes": Boolean,
-		"-y": "--yes",
-		"--install": Boolean,
-		"--no-install": Boolean,
-		"--package-manager": String,
-		"--show-install-output": Boolean,
-		"--git-init": Boolean,
-		"--no-git-init": Boolean,
-		"--help": Boolean,
-		"-h": "--help",
-		"--version": Boolean,
-		"--V": "--version",
-		"--no-color": Boolean,
-		"--no-motion": Boolean,
-		"--overwrite": Boolean
-	}, {
-		argv,
-		permissive: true
+	let { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		strict: false,
+		options: {
+			"agent-skills": { type: "boolean" },
+			debug: { type: "boolean" },
+			"git-init": { type: "boolean" },
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			install: { type: "boolean" },
+			"no-agent-skills": { type: "boolean" },
+			"no-color": { type: "boolean" },
+			"no-git-init": { type: "boolean" },
+			"no-install": { type: "boolean" },
+			"no-motion": { type: "boolean" },
+			overwrite: { type: "boolean" },
+			"package-manager": { type: "string" },
+			"react-router-version": {
+				type: "string",
+				short: "v"
+			},
+			"show-install-output": { type: "boolean" },
+			template: { type: "string" },
+			token: { type: "string" },
+			version: {
+				type: "boolean",
+				short: "V"
+			},
+			yes: {
+				type: "boolean",
+				short: "y"
+			}
+		}
 	});
-	let { "--debug": debug = false, "--help": help = false, "--react-router-version": selectedReactRouterVersion, "--template": template, "--token": token, "--install": install, "--no-install": noInstall, "--package-manager": pkgManager, "--show-install-output": showInstallOutput = false, "--git-init": git, "--no-git-init": noGit, "--no-motion": noMotion, "--yes": yes, "--version": versionRequested, "--overwrite": overwrite } = flags;
-	let cwd = flags["_"][0];
+	let getBooleanArg = (value) => typeof value === "boolean" ? value : void 0;
+	let getStringArg = (value) => typeof value === "string" ? value : void 0;
+	let selectedReactRouterVersion = getStringArg(values["react-router-version"]);
+	let yes = getBooleanArg(values.yes);
+	let cwd = positionals[0];
 	let interactive = isInteractive();
 	let projectName = cwd;
 	if (!interactive) yes = true;
@@ -1309,21 +1327,22 @@ async function getContext(argv) {
 	return {
 		tempDir: path.join(await realpath(os.tmpdir()), `create-react-router--${Math.random().toString(36).substr(2, 8)}`),
 		cwd,
-		overwrite,
+		overwrite: getBooleanArg(values.overwrite),
 		interactive,
-		debug,
-		git: git ?? (noGit ? false : yes),
-		help,
-		install: install ?? (noInstall ? false : yes),
-		showInstallOutput,
-		noMotion,
-		pkgManager: validatePackageManager(pkgManager ?? (process.env.npm_config_user_agent ?? "npm").split("/")[0]),
+		debug: getBooleanArg(values.debug) ?? false,
+		agentSkills: getBooleanArg(values["agent-skills"]) ?? (getBooleanArg(values["no-agent-skills"]) ? false : yes),
+		git: getBooleanArg(values["git-init"]) ?? (getBooleanArg(values["no-git-init"]) ? false : yes),
+		help: getBooleanArg(values.help) ?? false,
+		install: getBooleanArg(values.install) ?? (getBooleanArg(values["no-install"]) ? false : yes),
+		showInstallOutput: getBooleanArg(values["show-install-output"]) ?? false,
+		noMotion: getBooleanArg(values["no-motion"]),
+		pkgManager: validatePackageManager(getStringArg(values["package-manager"]) ?? detectPackageManager() ?? "npm"),
 		projectName,
 		prompt,
 		reactRouterVersion: selectedReactRouterVersion || version,
-		template,
-		token,
-		versionRequested
+		template: getStringArg(values.template),
+		token: getStringArg(values.token),
+		versionRequested: getBooleanArg(values.version)
 	};
 }
 async function introStep(ctx) {
@@ -1410,6 +1429,46 @@ async function copyTemplateToTempDirStep(ctx) {
 		ctx
 	});
 }
+async function agentSkillsQuestionStep(ctx) {
+	if (ctx.agentSkills === void 0) {
+		let { agentSkills = true } = await ctx.prompt({
+			name: "agentSkills",
+			type: "confirm",
+			label: title("skill"),
+			message: "Include the React Router agent skill?",
+			hint: "recommended",
+			initial: true
+		});
+		ctx.agentSkills = agentSkills;
+	}
+}
+async function copyAgentSkillsToAppDirStep(ctx) {
+	if (!ctx.agentSkills) {
+		await sleep(100);
+		info("Skipping agent skill.", [
+			"You can add it later from ",
+			color.reset("https://github.com/remix-run/react-router/tree/main/.agents/skills/react-router"),
+			"."
+		]);
+		return;
+	}
+	if (!existsSync(path.join(agentSkillPath, "SKILL.md"))) {
+		error("Oh no!", "React Router agent skill files were not found in this package.");
+		throw new Error("React Router agent skill files were not found");
+	}
+	let destPath = path.join(ctx.cwd, ".agents", "skills", "react-router");
+	if (existsSync(destPath)) {
+		info("Agent skill:", "React Router agent skill already included");
+		return;
+	}
+	await ensureDirectory(path.dirname(destPath));
+	await cp(agentSkillPath, destPath, {
+		errorOnExist: true,
+		force: false,
+		recursive: true
+	});
+	info("Agent skill:", "Included React Router agent skill");
+}
 async function copyTempDirToAppDirStep(ctx) {
 	await ensureDirectory(ctx.cwd);
 	let files1 = await getDirectoryFilesRecursive(ctx.tempDir);
@@ -1535,9 +1594,9 @@ async function gitInitStep(ctx) {
 			};
 			let commitMsg = "Initial commit from create-react-router";
 			try {
-				await execa("git", ["init"], options);
-				await execa("git", ["add", "."], options);
-				await execa("git", [
+				await runCommand("git", ["init"], options);
+				await runCommand("git", ["add", "."], options);
+				await runCommand("git", [
 					"commit",
 					"-m",
 					commitMsg
@@ -1559,12 +1618,12 @@ async function doneStep(ctx) {
 	await sleep(100);
 	if (projectDir !== "") {
 		let enter = [`\n${prefix}Enter your project directory using`, color.cyan(`cd .${path.sep}${projectDir}`)];
-		let len = enter[0].length + stripAnsi(enter[1]).length;
+		let len = enter[0].length + stripVTControlCharacters(enter[1]).length;
 		log(enter.join(len > max ? "\n" + prefix : " "));
 	}
 	log(`${prefix}Check out ${color.bold("README.md")} for development and deploy instructions.`);
 	await sleep(100);
-	log(`\n${prefix}Join the community at ${color.cyan(`https://rmx.as/discord`)}\n`);
+	log(`\n${prefix}Join the community at ${color.cyan(`https://remix.run/discord`)}\n`);
 	await sleep(200);
 }
 const validPackageManagers = [
@@ -1572,14 +1631,37 @@ const validPackageManagers = [
 	"yarn",
 	"pnpm",
 	"bun",
-	"deno"
+	"deno",
+	"nub"
 ];
 function validatePackageManager(pkgManager) {
 	return validPackageManagers.find((name) => pkgManager === name) ?? "npm";
 }
+/**
+* Determine which package manager the user prefers.
+*
+* npm, pnpm, Yarn, Bun, Deno, and nub set the user agent environment variable
+* that can be used to determine which package manager ran the command.
+*/
+function detectPackageManager() {
+	let { npm_config_user_agent } = process.env;
+	if (!npm_config_user_agent) return void 0;
+	try {
+		let pkgManager = npm_config_user_agent.split("/")[0];
+		if (pkgManager === "npm") return "npm";
+		if (pkgManager === "pnpm") return "pnpm";
+		if (pkgManager === "yarn") return "yarn";
+		if (pkgManager === "bun") return "bun";
+		if (pkgManager === "deno") return "deno";
+		if (pkgManager === "nub") return "nub";
+		return;
+	} catch {
+		return;
+	}
+}
 async function installDependencies({ pkgManager, cwd, showInstallOutput }) {
 	try {
-		await execa(pkgManager, ["install"], {
+		await runCommand(pkgManager, ["install"], {
 			cwd,
 			stdio: showInstallOutput ? "inherit" : "ignore"
 		});
@@ -1588,6 +1670,16 @@ async function installDependencies({ pkgManager, cwd, showInstallOutput }) {
 		throw err;
 	}
 }
+function runCommand(command, args, options) {
+	return new Promise((resolve, reject) => {
+		let child = spawn(command, args, options);
+		child.on("error", reject);
+		child.on("exit", (code, signal) => {
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(signal ? `${command} exited with signal ${signal}` : `${command} exited with code ${code}`));
+		});
+	});
+}
 async function updatePackageJSON(ctx) {
 	let packageJSONPath = path.join(ctx.cwd, "package.json");
 	if (!existsSync(packageJSONPath)) {
@@ -1652,6 +1744,7 @@ ${color.arg("--template <name>")}   ${color.dim(`The project template to use`)}
 ${color.arg("--[no-]install")}      ${color.dim(`Whether or not to install dependencies after creation`)}
 ${color.arg("--package-manager")}   ${color.dim(`The package manager to use`)}
 ${color.arg("--show-install-output")}   ${color.dim(`Whether to show the output of the install process`)}
+${color.arg("--[no-]agent-skills")} ${color.dim(`Whether or not to include the React Router agent skill`)}
 ${color.arg("--[no-]git-init")}     ${color.dim(`Whether or not to initialize a Git repository`)}
 ${color.arg("--yes, -y")}           ${color.dim(`Skip all option prompts and run setup`)}
 ${color.arg("--react-router-version, -v")}     ${color.dim(`The version of React Router to use`)}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-react-router",
   "type": "module",
-  "version": "8.0.1",
+  "version": "8.2.0",
   "description": "Create a new React Router app",
   "homepage": "https://reactrouter.com",
   "bugs": {
@@ -34,15 +34,12 @@
     }
   },
   "dependencies": {
-    "arg": "^5.0.1",
-    "execa": "9.6.1",
     "gunzip-maybe": "^1.4.2",
     "log-update": "^8.0.0",
     "picocolors": "^1.1.1",
     "semver": "^7.8.1",
     "sisteransi": "^1.0.5",
     "sort-package-json": "^3.6.1",
-    "strip-ansi": "^7.2.0",
     "tar-fs": "^3.1.2"
   },
   "devDependencies": {