remix-flat-routes

In addition to standard names (index, route, page, layout), any file prefixed with an underscore _ is treated as the route file. This allows you to name the file after the route itself for better discoverability within a folder.

Instead of _public.about/route.tsx, you can use _public.about/_about.tsx.

Hybrid routes allow you to use nested folders for route names while maintaining the colocation benefits of flat routes. This is useful for large apps with deep nesting or shared layouts (like _public or admin).

Instead of repeating long prefixes in every filename, you can create top-level folders and nest routes within them. This avoids the some.really.long.route.edit/index.tsx pattern found in standard flat routes.

# Example structure
app/routes-hybrid
├── _public
│   ├── _layout.tsx
│   └── about
│       └── _route.tsx
└── users
    ├── $userId
    │   └── _route.tsx
    └── _layout.tsx

To treat a folder as a flat file (effectively flattening its contents into the parent's namespace), append the nestedDirectoryChar (default is +) to the folder name.

Example: _auth+/forgot-password.tsx becomes _auth.forgot-password.tsx.

You can include _layout.tsx inside these folders, and you do not need to provide separate _public.tsx or users.tsx files.

# Example of folder with '+' suffix
_auth+/
├── forgot-password.tsx
└── login.tsx

# Results in routes: /forgot-password and /login under the _auth namespace

By default, flat-routes nests a route into the parent layout that has the longest matching prefix. For example, app.calendar.$day.tsx will nest inside app.calendar.tsx because app.calendar is the longest matching prefix.

To override this and nest a route under a higher-level layout (like root.tsx) instead of its immediate prefix match, append a trailing underscore (_) to the segment that is the immediate child of the route you want to skip.

Example:

• app_.projects.$id.roadmap.tsx will not nest under app.tsx or app.projects.tsx. It will nest directly under root.tsx because the app_ segment breaks the prefix match chain.

You can extend the routing capabilities of remix-flat-routes using the following patterns:

• Custom Param Prefix: Change the default $ to another character (e.g., ^) to avoid shell expansion issues. users.^userId.tsx becomes users/:userId.
• Custom Base Path: Override the default / to prepend a specific path to all routes.
• Optional Route Segments: Wrap a route name in parentheses to create an optional segment. parent.(optional).tsx becomes parent/optional?.

Use the migrate-flat-routes CLI tool to convert your existing Remix nested folder structure to the flat-routes convention.

npx migrate-flat-routes <sourceDir> <targetDir> [options]

Options:

• --convention=<convention>: Specifies the target format:
  • flat-files: Migrates to flat files.
  • flat-folders: Migrates to flat directories with index.tsx files.
  • hybrid: Keeps folder structure but uses + suffix and _layout files.
• --force: Overwrites the target directory if it already exists.

Example:

npx migrate-flat-routes ./app/routes ./app/flatroutes --convention=flat-folders

Note: sourceDir and targetDir are relative to your project root.

React Router v7 uses a new routing configuration. To use your existing Remix file-based routes, install the adapter and wrap your routes.ts configuration with remixRoutesOptionAdapter.

npm install -D @react-router/remix-routes-option-adapter
npm install -D remix-flat-routes

// app/routes.ts
import { remixRoutesOptionAdapter } from "@react-router/remix-routes-option-adapter";
import { flatRoutes } from "remix-flat-routes";

export default remixRoutesOptionAdapter((defineRoutes) => {
  return flatRoutes("routes", defineRoutes, {
    ignoredRouteFiles: ['**/.*'], // Ignore dot files (like .DS_Store)
  });
});

To use the flat-routes convention in your Remix project, install the package as a development dependency.

npm install -D remix-flat-routes

remix-flat-routes converts file-based naming conventions into standard URL patterns. It supports several special segment types:

Pathless layout routes are identified by filenames starting with a double underscore (__). These routes allow you to wrap child routes in a shared layout without adding a segment to the URL path.

Key Behaviors:

• Collision Handling: The library does not check for path collisions for pathless layout routes at the level where they are defined. This allows you to have multiple pathless layouts for the same URL segment if they reside in different subfolders.
• Example Structure:
  • routes/account/__public/login.tsx -> /account/login (via __public layout)
  • routes/account/__private/orders.tsx -> /account/orders (via __private layout)

However, collisions will still be detected if two different pathless routes attempt to claim the exact same child path, such as:

• routes/parent/__pathless/foo.tsx
• routes/parent/__pathless2/foo.tsx

The defineRoutes function is the core mechanism for building your route tree. It receives a callback that allows you to define routes and their nesting.

The defineRoute signature: defineRoute(path, file, children?)

• path: The relative URL path for the route.
• file: The absolute path to the route file.
• children (optional): A function used to define nested routes under this parent. If the route is an index route, providing a children function will throw an error.

Example Pattern:

flatRoutes('app/routes', (defineRoute) => {
  defineRoute('about', 'app/routes/about.tsx', () => {
    // Nested routes go here
    defineRoute('team', 'app/routes/about/team.tsx');
  });
});