Remix Flat Routes

All Contributors

This package enables you to define your routes using the flat-routes convention. This is based on the gist by Ryan Florence

βœ¨πŸŽ‰ New in v0.5.0

Remix v2 flat routes convention

remix-flat-routes was the initial implementation of the flat-routes specification. I added some enhancements based on user feedback. When Remix v2 added the flat-routes convention as the default, they used only the original specification.

If you want enhancements like hybrid routes, extended route filenames, custom param prefix, etc., you will need to continue to use this package.

remix-flat-routes will always maintain compatibility with the default Remix convention. This package is simply a superset/extension of the core convention.

NOTE: popular projects like Kent C. Dodds' Epic Stack uses remix-flat-routes

Hybrid Routes

You can now use nested folders for your route names, yet still keep the colocation feature of flat routes.

If you have a large app, its not uncommon to have routes nested many levels deep. With default flat routes, the folder name is the entire route path: some.really.long.route.edit/index.tsx

Often you may have several parent layouts like _public or admin. Instead of having to repeat the name in every route, you can create top-level folders, then nest your routes under them. This way you can still take advantage of flat folders with colocation.


❯ tree app/routes-folders
β”œβ”€β”€ _index
β”‚   └── page.tsx
β”œβ”€β”€ _public
β”‚   └── _layout.tsx
β”œβ”€β”€ _public.about
β”‚   └── index.tsx
β”‚   └── index.tsx
β”œβ”€β”€ test.$
β”‚   β”œβ”€β”€ _route.server.tsx
β”‚   └── _route.tsx
β”œβ”€β”€ users
β”‚   β”œβ”€β”€ _layout.tsx
β”‚   └── users.css
β”œβ”€β”€ users.$userId
β”‚   β”œβ”€β”€ _route.tsx
β”‚   └── avatar.png
β”œβ”€β”€ users.$userId_.edit
β”‚   └── _route.tsx
└── users._index
    └── index.tsx


❯ tree app/routes-hybrid
β”œβ”€β”€ _index
β”‚   └── index.tsx
β”œβ”€β”€ _public
β”‚   β”œβ”€β”€ _layout.tsx
β”‚   β”œβ”€β”€ about
β”‚   β”‚   └── _route.tsx
β”‚   └── contact[.jpg]
β”‚       └── _route.tsx
β”œβ”€β”€ test.$
β”‚   └── _route.tsx
└── users
    β”œβ”€β”€ $userId
    β”‚   β”œβ”€β”€ _route.tsx
    β”‚   └── avatar.png
    β”œβ”€β”€ $userId_.edit
    β”‚   └── _route.tsx
    β”œβ”€β”€ _index
    β”‚   └── index.tsx
    β”œβ”€β”€ _layout.tsx
    └── users.css

Nested folders with flat-files convention (✨ New in v0.5.1)

To create a folder but treat it as flat-file, just append the +to the folder name.

_auth+/forgot-password.tsx => _auth.forgot-password.tsx

NOTE: You can include the _layout.tsx file inside your folder. You do NOT need to have a _public.tsx or users.tsx file.

You can still use flat-folders for colocation. So this is best of both formats.

❯ tree app/routes-hybrid-files/
β”œβ”€β”€ _auth+
β”‚   β”œβ”€β”€ forgot-password.tsx
β”‚   └── login.tsx
β”œβ”€β”€ _public+
β”‚   β”œβ”€β”€ _layout.tsx
β”‚   β”œβ”€β”€ about.tsx
β”‚   β”œβ”€β”€ contact[.jpg].tsx
β”‚   └── index.tsx
β”œβ”€β”€ project+
β”‚   β”œβ”€β”€ _layout.tsx
β”‚   β”œβ”€β”€ parent.child
β”‚   β”‚   └── index.tsx
β”‚   └── parent.child.grandchild
β”‚       β”œβ”€β”€ index.tsx
β”‚       └── styles.css
└── users+
    β”œβ”€β”€ $userId.tsx
    β”œβ”€β”€ $userId_.edit.tsx
    β”œβ”€β”€ _layout.tsx
    └── index.tsx
  <Route file="root.tsx">
    <Route path="login" file="routes-hybrid-files/_auth+/login.tsx" />
    <Route file="routes-hybrid-files/_public+/_layout.tsx">
      <Route path="about" file="routes-hybrid-files/_public+/about.tsx" />
      <Route index file="routes-hybrid-files/_public+/index.tsx" />
    <Route path="project" file="routes-hybrid-files/project+/_layout.tsx">
    <Route path="users" file="routes-hybrid-files/users+/_layout.tsx">
      <Route path=":userId" file="routes-hybrid-files/users+/$userId.tsx" />
      <Route index file="routes-hybrid-files/users+/index.tsx" />

Extended Route Filenames

In addition to the standard index | route | page | layout names, any file that has a _ prefix will be treated as the route file. This will make it easier to find a specific route instead of looking through a bunch of route.tsx files. This was inspired by SolidStart "Renaming Index" feature.

So instead of


You can name them


Multiple Route Folders

You can now pass in additional route folders besides the default routes folder. These routes will be merged into a single namespace, so you can have routes in one folder that will use shared routes from another.

Custom Param Prefix

You can override the default param prefix of $. Some shells use the $ prefix for variables, and this can be an issue due to shell expansion. Use any character that is a valid filename, for example: ^

users.^userId.tsx  => users/:userId
test.^.tsx         => test/*

Custom Base Path

You can override the default base path of /. This will prepend your base path to the root path.

Optional Route Segments

React Router will introduce a new feature for optional route segments. To use optional segments in flat routes, simply wrap your route name in ().

parent.(optional).tsx   => parent/optional?

Custom App Directory

You can override the default app directory of app.

πŸ›  Installation

npm install -D remix-flat-routes

βš™οΈ Configuration

Update your remix.config.js file and use the custom routes config option.

const { flatRoutes } = require('remix-flat-routes')

 * @type {import("@remix-run/dev").AppConfig}
module.exports = {
  // ignore all files in routes folder to prevent
  // default remix convention from picking up routes
  ignoredRouteFiles: ['**/*'],
  routes: async defineRoutes => {
    return flatRoutes('routes', defineRoutes)


function flatRoutes(
  routeDir: string | string[],
  defineRoutes: DefineRoutesFunction,
  options: FlatRoutesOptions,

type FlatRoutesOptions = {
  appDir?: string // optional app directory (defaults to app)
  basePath?: string // optional base path (default is '/')
  paramPrefixChar?: string // optional param prefix (default is '$')
  ignoredRouteFiles?: string[] // optional files to ingore as routes (same as Remix config option)
  visitFiles?: VisitFilesFunction // optional visitor (useful for tests to provide files without file system)

NOTE: routeDir should be relative to the app folder. If you want to use the routes folder, you will need to update the ignoredRouteFiles property to ignore all files: **/*

πŸ”¨ Flat Routes Convention

Example (flat-files)


As React Router routes:

  <Route element={<Auth />}>
    <Route path="forgot-password" element={<Forgot />} />
    <Route path="login" element={<Login />} />
    <Route path="reset-password" element={<Reset />} />
    <Route path="signup" element={<Signup />} />
  <Route element={<Landing />}>
    <Route path="about" element={<About />} />
    <Route index element={<Index />} />
  <Route path="app" element={<App />}>
    <Route path="calendar" element={<Calendar />}>
      <Route path=":day" element={<Day />} />
      <Route index element={<CalendarIndex />} />
    <Route path="projects" element={<Projects />}>
      <Route path=":id" element={<Project />} />
  <Route path="app/projects/:id/roadmap" element={<Roadmap />} />
  <Route path="app/projects/:id/roadmap.pdf" />

Individual explanations:

filename url nests inside of...
_auth.forgot-password.tsx /forgot-password _auth.tsx
_auth.login.tsx /login _auth.tsx
_auth.reset-password.tsx /reset-password _auth.tsx
_auth.signup.tsx /signup _auth.tsx
_auth.tsx n/a root.tsx
_landing.about.tsx /about _landing.tsx
_landing.index.tsx / _landing.tsx
_landing.tsx n/a root.tsx
app.calendar.$day.tsx /app/calendar/:day app.calendar.tsx
app.calendar.index.tsx /app/calendar app.calendar.tsx
app.projects.$id.tsx /app/projects/:id app.projects.tsx
app.projects.tsx /app/projects app.tsx
app.tsx /app root.tsx
app_.projects.$id.roadmap.tsx /app/projects/:id/roadmap root.tsx
app_.projects.$id.roadmap[.pdf].tsx /app/projects/:id/roadmap.pdf n/a (resource route)

Nested Layouts

Default match

By default, flat-routes will nest the current route into the parent layout that has the longest matching prefix.

Given the layout route app.calendar.tsx, the following routes will be nested under app.calendar.tsx since app.calendar is the longest matching prefix.

  • app.calendar.index.tsx
  • app.calendar.$day.tsx

Override match

Sometimes you want to use a parent layout that is higher up in the route hierarchy. With the default Remix convention, you would use dot (.) notation instead of nested folders. With flat-routes, since routes files always use dots, there is a different convention to specify which layout to nest under.

Let's say you have an app.tsx layout, and you have a route that you don't want to share with the layout, but instead want to match with root.tsx. To override the default parent match, append a trailing underscore (_) to the segment that is the immediate child of the route you want to nest under.

app_.projects.$id.roadmap.tsx will nest under root since there are no matching routes:

  • ❌ app_.projects.$id.tsx
  • ❌ app_.projects.tsx
  • ❌ app_.tsx
  • βœ… root.tsx


filename convention behavior
privacy.jsx filename normal route
pages.tos.jsx dot with no layout normal route, . -> /
about.jsx filename with children parent layout route dot child route of layout
about.index.jsx index filename index route of layout
about._index.jsx alias of index.tsx index route of layout* trailing underscore url segment, no layout
app_.projects.$id.roadmap.tsx trailing underscore change default parent layout
_auth.jsx leading underscore layout nesting, no url segment
_auth.login.jsx leading underscore child of pathless layout route
users.$userId.jsx leading $ URL param
docs.$.jsx bare $ splat route
dashboard.route.jsx route suffix optional, ignored completely
investors/[index].jsx brackets escapes conventional characters

NOTE: The underscore prefix for the index route is optional but helps sort the file to the top of the directory listing.


  • Make it easier to see the routes your app has defined - just pop open "routes/" and they are all right there. Since file systems typically sort folders first, when you have dozens of routes it's hard to see today which folders have layouts and which don't. Now all related routes are sorted together.

  • Decrease refactor/redesign friction - while code editors are pretty good at fixing up imports when you move files around, and Remix has the "~" import alias, it's just generally easier to refactor a code base that doesn't have a bunch of nested folders. Remix will no longer force this.

    Additionally, when redesigning the user interface, it's simpler to adjust the names of files rather than creating/deleting folders and moving routes around to change the way they nest.

  • Help apps migrate to Remix - Existing apps typically don't have a nested route folder structure like today's conventions. Moving to Remix is arduous because you have to deal with all of the imports.


While the example is exclusively files, they are really just "import paths". So you could make a folder for a route instead and the index file will be imported, allowing all of a route's modules to live alongside each other. This is the flat-folders convention, as opposed to the flat-files convention detailed above.

Example (flat-folders)


Each route becomes a folder with the route name minus the file extension. The route file then is named index.tsx.

So app.projects.tsx becomes app.projects/index.tsx

    index.tsx x <- route file (same as _auth.tsx)
    index.tsx  <- route file (same as _auth.forgot-password.tsx)
    index.tsx   <- route files (same as _auth.login.tsx)
    index.tsx   <- route file (same as _landing.about.tsx)
    index.tsx   <- route file (same as _landing.index.tsx)
    index.tsx   <- route file (same as _landing.tsx)
    index.tsx   <- route file (same as app.tsx)
    index.tsx   <- route file (same as app_.projects.$id.roadmap.tsx)
    index.tsx <- layout file (sames as app.projects.tsx)
    index.tsx  <- route file (sames as app.projects.$id.tsx)


Since the route file is now named index.tsx and you can colocate additional files in the same route folder, the index.tsx file may get lost in the list of files. You can also use the following aliases for index.tsx. The underscore prefix will sort the file to the top of the directory listing.

  • _index.tsx
  • _layout.tsx
  • _route.tsx

NOTE: The _layout.tsx and _route.tsx files are simply more explicit about their role. They work the same as index.tsx.

As with flat files, an index route (not to be confused with index route file), can also use the underscore prefix. The route _landing.index can be saved as _landing.index/index.tsx or _landing._index/_index.tsx.

This is a bit more opinionated, but I think it's ultimately what most developers would prefer. Each route becomes its own "mini app" with all of its dependencies together. With the ignoredRouteFiles option it's completely unclear which files are routes and which aren't.

🚚 Migrating Existing Routes

You can now migrate your existing routes to the new flat-routes convention. Simply run:

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

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

  sourceDir and targetDir are relative to project root

    The convention to use when migrating.
      flat-files - Migrates to flat files
      flat-folders - Migrates to flat directories with route.tsx files
      hybrid - Keep folder structure with '+' suffix and _layout files
    Overwrite target directory if it exists

😍 Contributors

Thanks goes to these wonderful people (emoji key):


πŸ’» πŸ“–

Ryan Florence


Brandon Pittman

πŸ“– πŸ’»

Mehdi Achour


Fidel GonzΓ‘lez


Andrew Haines


Wonu Lee


Markus Wolf


Sarat Chandra Balla


This project follows the all-contributors specification. Contributions of any kind welcome!