AGENTS.md · remix-run/react-router

Sections

1. Commands
2. Modes
3. Architecture
4. Testing
5. routes.ts
6. Documentation
7. Future Flags
8. License
9. Change Files
10. Branching
11. Key Files

First lines (shown under the repo's MIT license)

# React Router Development Guide

## Commands

- **Build**: `pnpm build` (all packages) or `pnpm run --filter <package> build` (single package)
- **Test (Jest)**: `pnpm test` (all packages), `pnpm test packages/<package>/` (single package), `pnpm test packages/react-router/__tests__/router/fetchers-test.ts` (single file), or `pnpm test -- -t "action fetch"` (tests matching name)
- **Integration tests (Playwright)**: `pnpm test:integration --project chromium` (build + test all), `pnpm test:integration:run --project chromium` (test only, all), `pnpm test:integration:run integration/middleware-test.ts --project chromium` (single file), or `pnpm test:integration:run --project chromium -g "middleware"` (tests matching name)
- **Typecheck**: `pnpm run typecheck`
- **Lint**: `pnpm run lint`
- **Docs generation**: `pnpm run docs` (regenerates API docs from JSDoc)
- **Type generation**: `pnpm run typegen` (Framework Mode only)
- **Clean**: `pnpm run clean` (git clean -fdX)

## Modes

**Five distinct modes**: Declarative, Data, Framework, RSC Data (unstable), RSC Framework (unstable). **Always identify which mode(s) a feature applies to.**

1. **Declarative**: `<BrowserRouter>`, `<Routes>`, `<Route>`
2. **Data**: `createBrowserRouter()` with `loader`/`action`, `<RouterProvider>`
3. **Framework**: Vite plugin + `routes.ts` + Route Module API (route exports like `loader`, `action`, `default`) + type generation + SSR/SPA
4. **RSC Data** (unstable): RSC runtime APIs, manual bundler setup, runtime route config
5. **RSC Framework** (unstable): Framework Mode with `unstable_reactRouterRSC` Vite plugin

**RSC mode differences:**

- **RSC Framework**: `unstable_reactRouterRSC` plugin, `@vitejs/plugin-rsc`, different entry points/format
- **RSC Data**: Manual bundler, runtime route config typically in `src/routes.ts`, `unstable_RSCRouteConfig`, different runtime APIs, `setupRscTest` in `integration/rsc/`

## Architecture

- **Monorepo**: pnpm workspace, packages in `packages/`
- **Key packages**:
  - `react-router`: Core (all modes) - `lib/components.tsx`, `lib/hooks.tsx`, `lib/router/`, `lib/dom/`, `lib/rsc/`
  - `@react-router/dev`: Framework tooling - `vite/plugin.ts` (Framework), `vite/rsc/plugin.ts` (RSC Framework), `typegen/`
  - `@react-router/node`, `@react-router/cloudflare`, `@react-router/express`: Server adapters
  - `@react-router/serve`: Minimal server for Framework Mode
  - `@react-router/fs-routes`: File-system routing (`flatRoutes()`)

## Testing

### Unit Tests (`packages/react-router/__tests__/`)

Use Jest for pure routing logic, pure server runtime behavior, router state, React component behavior. No build required.

```bash
pnpm test                                                          # All packages
pnpm test packages/react-router/                                   # Single package
pnpm test packages/react-router/__tests__/router/fetchers-test.ts  # Single file
pnpm test -- -t "action fetch"                                     # Tests matching name
```

### Integration Tests (`integration/`)

Use Playwright for Vite plugin, build pipeline, SSR/hydration, RSC, type generation.

```bash
pnpm test:integration --project chromium                                     # Build + test all
pnpm test:integration:run --project chromium                                 # Test only, all
pnpm test:integration:run integration/middleware-test.ts --project chromium  # Single file
pnpm test:integration:run --project chromium -g "middleware"                 # Tests matching name
```

**Project**: Always use `chromium` for integration tests, unless explicitly stated otherwise.

**Rebuild when**: First run, after changing `packages/` (not needed for test-only changes)

**Organization**: Use `createFixture()` → `createAppFixture()` → `PlaywrightFixture`. Templates available: `vite-6-template/`, `rsc-vite-framework/`, etc. Test all applicable modes (iterate over template array when behavior should work across modes). Test both states when introducing future flags (one test with flag on, one with flag off).

**RSC testing**:

- **RSC Framework**: Use `createFixture` with `rsc-vite-framework/` template
- **RSC Data**: Use `setupRscTest` in `integration/rsc/`

Test shared behavior across multiple templates (e.g., `["vite-5-template", "rsc-vite-framework"]`). Test RSC-specific features against RSC template.

## routes.ts

Framework Mode uses `routes.ts` in `app/`. Most tests use `flatRoutes()` for file-system routing:

```ts
// app/routes.ts
import { type RouteConfig } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";

export default flatRoutes() satisfies RouteConfig;
```

**File-system conventions** (`app/routes/`):

- `_index.tsx` → `/` (index route)
- `about.tsx` → `/about`
- `blog.$slug.tsx` → `/blog/:slug` (URL param)
- `settings.profile.tsx` → `/settings/profile` (`.` creates nesting)
- `_layout.tsx` → pathless layout route

**Manual config alternative**:

```ts
import { index, route, layout } from "@react-router/dev/routes";
export default [
  index("./home.tsx"),
  route("about", "./about.tsx"),
  layout("./auth-layout.tsx", [route("login", "./login.tsx")]),
];
```

## Documentation

**Don't edit generated files**: `docs/api/` (from JSDoc), `.react-router/types/` (from typegen)

**Mode indicators**: Every doc needs `[MODES: framework, data, declarative]`

**API docs**: Edit JSDoc in `packages/react-router/lib/`, run `pnpm docs`

**Unstable features**: Prefix `unstable_`, add `unstable: true` to frontmatter, include warning block

## Future Flags

- **Future flags** (`vX_*`): Stable breaking changes for next major
- **Unstable flags** (`unstable_*`): Experimental, may change

Test both states (on/off) for future flags. Don't break existing behavior without a flag.

## License

By contributing to React Router, you agree that your contributions will be licensed under the [MIT License](./LICENSE.md).

## Change Files

When making changes that affect users, create a change file at `packages/<package>/.changes/<type>.<unique-meaningful-name>.md`. `<type>` should be either `patch`, `minor`, `major` or `unstable` to indicate the type of API change being made. If iterating on a change that hasn't shipped yet, update the existing change file instead of creating a new one.

Format:

```markdown
Brief description of the change

- Additional details if needed
```

## Branching

- **`main`**: Active Development
- **`v7`**: v7.x maintenance
- **`v6`**: v6.x maintenance
- Branch from `main` for code and docs changes

## Key Files

| Purpose           | Location                                                    |
| ----------------- | ----------------------------------------------------------- |
| Router            | `packages/react-router/lib/router/router.ts`                |
| React API         | `packages/react-router/lib/components.tsx`, `lib/hooks.tsx` |
| Vite plugin       | `packages/react-router-dev/vite/plugin.ts`                  |
| RSC Vite plugin   | `packages/react-router-dev/vite/rsc/plugin.ts`              |
| Type generation   | `packages/react-router-dev/typegen/`                        |
| Unit tests        | `packages/react-router/__tests__/`                          |
| Integration tests | `integration/`                                              |
| Decision docs     | `decisions/`                                                |