react-router-auto-routes - GitLite

KO | EN

gitlite — search

#react #typescript #golang #android #machine-learning #linux #docker #java #windows #awesome-list #vue #security #mcp #open-source

react-router-auto-routes

(★ 101)

Automatic folder-based routing with colocation for React Router v7+

파일 탐색기

최종 버전 다운로드 (.zip)

- - claude-code-review.yml
  - claude.yml
- - index.ts
  - types.ts
- - visit-files.ts
- - cli.ts
  - constants.ts
  - create-routes-from-folders.ts
  - fs-helpers.ts
  - import-rewriter.ts
  - logger.ts
  - migrate.ts
  - normalizers.ts
  - parser.ts
  - route-definition.ts
  - route-scanner.ts
- index.ts
- utils.ts
- - route-test-helpers.ts
  - tmp-workspace.ts
- filesystem-behavior.test.ts
- fs-visit-files.test.ts
- migrate-cli.test.ts
- migration-convert-to-route.test.ts
- migration-create-route-path.test.ts
- migration-fs-helpers.test.ts
- migration-import-rewriter.test.ts
- options-and-detection.test.ts
- routes-structure.test.ts
.gitignore
.oxfmtrc.json
AGENTS.md
CLAUDE.md
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
tsconfig.build.json
tsconfig.json
tsup.config.ts
vitest.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# React Router Auto Routes

Automatic folder-based routing with colocation for React Router v7+.

## Principles

Built on [convention-over-configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) principles—your file structure defines your routes automatically, with smart defaults that just work, and scale well.

[Colocation](https://kentcdodds.com/blog/colocation) is a first-class feature:

> "Place code as close to where it's relevant as possible" — Kent C. Dodds

Keep your components, tests, utilities, and routes together. No more hunting across folders or artificial separation of concerns. The `+` prefix marks non-route files for cohesive, feature-based code organization.

## Features

- 📁 **Flexible file organization** - Mix and match folder-based and dot-delimited notation
- 🎯 **Prefix-based colocation** - Keep helpers and components alongside routes using `+` prefix
- 📦 **Monorepo / sub-apps support** - Mount routes from different folders to organize multi-app projects
- ⚡ **ESM-only** - No CommonJS, built for modern tooling
- 🧹 **Clean API** - Simplified options and intuitive conventions

## Quick Start

Install:

```bash
npm install -D react-router-auto-routes
```

Use in your app:

```ts
// app/routes.ts
import { autoRoutes } from 'react-router-auto-routes'

export default autoRoutes()
```

> **Migrating from remix-flat-routes?** See the [Migration Guide](#migration-guide) below.

## Routing Convention

**Folder-based structure:**

```
routes/
├── index.tsx            → / (index route)
├── about.tsx            → /about
├── robots[.]txt.ts      → /robots.txt (literal dot segment)
├── _auth/               → Pathless layout (no /auth in URL)
│   ├── _layout.tsx      → Auth layout
│   ├── login.tsx        → /login
│   └── signup.tsx       → /signup
├── blog/
│   ├── _layout.tsx      → Layout for /blog/* routes
│   ├── index.tsx        → /blog
│   ├── $slug.tsx        → /blog/:slug (dynamic param)
│   └── archive.tsx      → /blog/archive
├── dashboard/
│   ├── _layout.tsx      → Layout for dashboard routes
│   ├── index.tsx        → /dashboard
│   ├── analytics.tsx    → /dashboard/analytics
│   └── settings/
│       ├── _layout.tsx  → Layout for settings routes
│       ├── index.tsx    → /dashboard/settings
│       └── profile.tsx  → /dashboard/settings/profile
└── files/
    └── $.tsx            → /files/* (splat - catch-all)
```

**Equivalent flat (dot-delimited) structure:**

```
routes/
├── index.tsx                          → / (index route)
├── about.tsx                          → /about
├── robots[.]txt.ts                    → /robots.txt (literal dot segment)
├── _auth._layout.tsx                  → Auth layout
├── _auth.login.tsx                    → /login
├── _auth.signup.tsx                   → /signup
├── blog._layout.tsx                   → Layout for /blog/* routes
├── blog.index.tsx                     → /blog
├── blog.$slug.tsx                     → /blog/:slug (dynamic param)
├── blog.archive.tsx                   → /blog/archive
├── dashboard._layout.tsx              → Layout for dashboard routes
├── dashboard.index.tsx                → /dashboard
├── dashboard.analytics.tsx            → /dashboard/analytics
├── dashboard.settings._layout.tsx     → Layout for settings routes
├── dashboard.settings.index.tsx       → /dashboard/settings
├── dashboard.settings.profile.tsx     → /dashboard/settings/profile
└── files.$.tsx                        → /files/* (splat - catch-all)
```

Both structures produce identical routes. Use folders for organization, flat files for simplicity, or mix both approaches as needed.

### Route Patterns

| Pattern                    | Meaning                                                                                                                                               | Example                                          |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `index.tsx` / `_index.tsx` | Index route — the default page for a folder. Automatically nests under a matching `_layout.tsx`.                                                      | `blog/index.tsx` → `/blog`                       |
| `_layout.tsx`              | Shared layout wrapper (renders an `<Outlet />`). The **only** file that creates nesting. `layout.tsx` without `_` is just a normal route (`/layout`). | `blog/_layout.tsx` wraps all `/blog/*` pages     |
| `_` prefix folder          | Groups routes under a shared layout **without** adding a URL segment                                                                                  | `_auth/login.tsx` → `/login` (not `/auth/login`) |
| `$param`                   | Dynamic segment — matches any value in that position                                                                                                  | `$slug.tsx` → `/blog/:slug`                      |
| `$.tsx`                    | Catch-all (splat) — matches everything after this point                                                                                               | `files/$.tsx` → `/files/*`                       |
| `(segment)`                | Optional segment — matches with or without it                                                                                                         | `(en)/about.tsx` → `/en?/about`                  |
| `($param)`                 | Optional dynamic segment                                                                                                                              | `($lang)/home.tsx` → `/:lang?/home`              |
| `[.]`                      | Literal dot — escapes the dot so it's part of the URL                                                                                                 | `robots[.]txt.ts` → `/robots.txt`                |

**Key insight:** Folders are just organization. Without a `_layout.tsx` in the folder, `api/users.ts` behaves like `api.users.ts` — both create a route at `/api/users`.

### Route Ordering

When multiple routes could match the same URL, order matters. Routes are sorted by these rules (first match wins):

1. **Fewer segments first** — `/about` before `/about/team`
2. **Non-index routes before index routes**
3. **Layouts before regular routes**
4. **More specific paths first** — `/users/new` before `/users/:id` before `/users/*`
5. **Alphabetical** by route ID as a final tiebreaker

## Colocation with `+` Prefix

Keep helpers, components, and utilities alongside routes using the `+` prefix. Anything starting with `+` is ignored by the router.

```
routes/
├── dashboard/
│   ├── index.tsx          → Route: /dashboard
│   ├── +/
│   │   ├── helpers.ts
│   │   └── types.tsx
│   └── +components/
│       └── data-table.tsx
└── users/
    ├── index.tsx          → Route: /users
    ├── +user-list.tsx
    └── $id/
        ├── index.tsx      → Route: /users/:id
        ├── edit.tsx       → Route: /users/:id/edit
        └── +/
            ├── query.ts
            └── validation.ts
```

Import colocated files using relative paths:

```ts
import { formatDate } from './+/helpers'
```

**Rules:**

- **Allowed:** Use `+` prefixed files and folders anywhere inside route directories (e.g., `+helpers.ts`, `+.tsx`, or `+/` folders)
- **Disallowed:** Don't place `+` entries at the routes root level like `routes/+helpers.ts` (but `routes/_top/+helpers.ts` is fine)
- **Note:** `+types` is [reserved](https://reactrouter.com/explanation/type-safety) for React Router's typegen virtual folders so avoid that name.

## Configuration Options

```ts
autoRoutes({
  routesDir: 'routes',
  ignoredRouteFiles: ['**/.*'], // Ignore dotfiles like .gitkeep
  paramChar: '$',
  colocationChar: '+',
  routeRegex: /\.(ts|tsx|js|jsx|md|mdx)$/,
})
```

`.DS_Store` is always ignored automatically, even when you provide custom `ignoredRouteFiles`, and the migration CLI inherits the same default.

**Note:** Prefer the `+` colocation prefix over `ignoredRouteFiles` when possible. Files ignored via `ignoredRouteFiles` are completely invisible to the router — it won't warn you if they accidentally shadow a route. Colocated `+` files are still validated, so you'll get helpful errors if something is misplaced. For example, place tests in `+test/` folders rather than using `**/*.test.{ts,tsx}` in `ignoredRouteFiles`.

<details>
<summary><strong>Advanced: Directory resolution</strong></summary>

- Paths in `routesDir` are always relative to your project root. You can use `'../pages'` to point outside the app folder.
- When you mount `/` to a folder, generated import paths are kept short relative to that folder's parent (e.g., `'/': 'packages/web/routes'` produces `routes/*` imports, not `../packages/web/routes/*`).
- Without a `/` mount, the app directory defaults to `<project>/app`. Override this with `globalThis.__reactRouterAppDirectory` if your app lives elsewhere (e.g., `app/router`).

</details>

### Monorepo / Sub-apps (Multiple Route Roots)

`routesDir` accepts two shapes:

- `string` – scan a single root. When omitted, the default `'routes'` resolves to `app/routes` so existing folder structures continue to work with zero config.
- `Record<string, string>` – mount filesystem folders to URL paths (key = URL path, value = filesystem folder). Folder paths resolve from the project root so you can mount packages that live outside `app/`.

Mount routes from different folders to organize sub-apps or monorepo packages:

```ts
autoRoutes({
  routesDir: {
    '/': 'app/routes',
    '/api': 'api/routes',
    '/docs': 'packages/docs/routes',
    '/shop': 'packages/shop/routes',
  },
})
```

**Example structure:**

```
app/
  routes/
    dashboard.tsx                  → /dashboard
    settings/
      _layout.tsx                  → /settings (layout)
      index.tsx                    → /settings
api/
  routes/
    users/
      index.tsx                    → /api/users
packages/
  docs/
    routes/
      index.tsx                    → /docs
  shop/
    routes/
      index.tsx                    → /shop
```

Routes from each mount stay isolated when resolving parents and dot-flattening, but still merged into a single manifest.

## Recipes

### CMS / Catch-all Routes

For a CMS-style setup where you want a homepage (`/`) and a catch-all for dynamic pages (`/*`), use a separate `index.tsx` and `$.tsx`.

```
routes/
├── index.tsx          → Homepage (/)
└── $.tsx              → Catch-all (/*)
```

**Why?**
Using an optional splat `($).tsx` can cause issues with error boundaries bubbling up unexpectedly in React Router v7. Separating them ensures:

1. The homepage has its own explicit route and data requirements.
2. The catch-all route handles everything else (404s or dynamic CMS pages) without interfering with the root layout's error handling.

## Migration Guide

> **Note:** This migration tool is designed for projects using [remix-flat-routes](https://github.com/kiliman/remix-flat-routes) 0.8.\*

This library preserves `remix-flat-routes` sibling behavior: dot-delimited routes remain siblings by default and only nest under explicit `_layout` files.

If you want `edit` to render inside a layout, add a layout file and (optionally) move the detail view to `index.tsx`:

```
routes/
└── users/
    └── $id/
        ├── _layout.tsx  → Layout for /users/:id/*
        ├── index.tsx    → /users/:id (The detail view)
        └── edit.tsx     → /users/:id/edit (The edit view)
```

The migration tool continues to follow legacy `remix-flat-routes` semantics and will promote parent routes to `_layout` when children exist.

### CLI Migration

Install the package, then run the migration CLI:

```bash
npx migrate-auto-routes

# or provide an explicit [source] [destination]
npx migrate-auto-routes app/routes app/new-routes
```

The CLI overwrites the target folder if it already exists. With no arguments it reads from `app/routes` and writes to `app/new-routes`. When you pass both arguments, the CLI uses the exact `sourceDir` and `targetDir` paths you provide.

**Built-in safety checks:** The CLI performs these automatically so you don’t have to.

- Verifies you are inside a Git repository and the route source folder (e.g. `app/routes`) has no pending changes before running the migration CLI
- Runs `npx react-router routes` before and after rewriting files
- Parses every JavaScript and TypeScript route before writing migrated files; syntax errors stop the migration before the target is modified
- Stages the migrated result in `app/new-routes` (or your custom target) before swapping it into place
- If successful, renames `app/routes` to `app/old-routes`, then moves the new routes into `app/routes`
- If the generated route output differs, prints a diff, restores the original folder, and keeps the migrated files at the target path for inspection
- When your project still imports `createRoutesFromFolders`/`remix-flat-routes`, the CLI updates `app/routes.ts` to export `autoRoutes()` so the snapshot check runs against the migrated tree

Route-entry conversion stops with an actionable error when the legacy call cannot be identified safely—for example, when it is imported under an alias—or when extracted options reference local bindings. Inline those option values or update the entry manually, then rerun the migration. This prevents the CLI from replacing a customized entry with an incomplete `autoRoutes()` call.

If everything looks good, you can uninstall the old packages:

```bash
npm uninstall remix-flat-routes
npm uninstall @react-router/remix-routes-option-adapter
```

### Deprecating `route.tsx`

Deprecating legacy `route.tsx` files in favor of `index.tsx` plus `+` colocation. Support remains for now, after which the matcher will be removed.

If you used `route.tsx` as the entry point for colocated helpers, follow these steps:

1. Move any colocated assets (loaders, helpers, tests) into a `+/` folder so they stay adjacent without being treated as routes.
2. Rename each `route.tsx` to `index.tsx` inside its directory so the folder name becomes the route segment.
3. Run `npx react-router routes` to confirm the manifest compiles cleanly and no lingering `route.tsx` entries remain. Double-check that colocated helpers stayed inside `+/` folders so they are not accidentally exposed as routes.

The migration CLI still recognizes `route.tsx` right now for backwards compatibility, but future releases will warn (and eventually drop support) once projects have had a full cycle to adopt the `index.tsx` pattern.

## Requirements

- Node.js ^20.19.0 or >= 22.12.0
- React Router v7+

## Acknowledgments

This library is heavily inspired by [remix-flat-routes](https://github.com/kiliman/remix-flat-routes) by @kiliman. While this is a complete rewrite for React Router v7+, the core routing conventions and ideas stem from that excellent work.