Remix Flat Routes

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

💡 React Router v7 Support

React Router v7 uses a new routing config. To ease migration from Remix, the team has published an adapter package that will convert existing Remix file-based routes to the new config format.

To use your existing file-based routing, install the adapter and update routes.ts to wrap your adapter.

1npm install -D @react-router/remix-config-routes-adapter
2npm install -D remix-flat-routes

1// app/routes.ts
2import { remixConfigRoutes } from "@react-router/remix-config-routes-adapter";
3import { flatRoutes } from "remix-flat-routes";
4
5export const routes = remixConfigRoutes((defineRoutes) => {
6  return flatRoutes("routes", defineRoutes, {/* options */});
7});

✨🎉 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.

Before

1❯ tree app/routes-folders
2app/routes-folders
3├── _index
4│   └── page.tsx
5├── _public
6│   └── _layout.tsx
7├── _public.about
8│   └── index.tsx
9├── _public.contact[.jpg]
10│   └── index.tsx
11├── test.$
12│   ├── _route.server.tsx
13│   └── _route.tsx
14├── users
15│   ├── _layout.tsx
16│   └── users.css
17├── users.$userId
18│   ├── _route.tsx
19│   └── avatar.png
20├── users.$userId_.edit
21│   └── _route.tsx
22└── users._index
23    └── index.tsx

After

1❯ tree app/routes-hybrid
2app/routes-hybrid
3├── _index
4│   └── index.tsx
5├── _public
6│   ├── _layout.tsx
7│   ├── about
8│   │   └── _route.tsx
9│   └── contact[.jpg]
10│       └── _route.tsx
11├── test.$
12│   └── _route.tsx
13└── users
14    ├── $userId
15    │   ├── _route.tsx
16    │   └── avatar.png
17    ├── $userId_.edit
18    │   └── _route.tsx
19    ├── _index
20    │   └── index.tsx
21    ├── _layout.tsx
22    └── 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/
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

1<Routes>
2  <Route file="root.tsx">
3    <Route
4      path="forgot-password"
5      file="routes-hybrid-files/_auth+/forgot-password.tsx"
6    />
7    <Route path="login" file="routes-hybrid-files/_auth+/login.tsx" />
8    <Route file="routes-hybrid-files/_public+/_layout.tsx">
9      <Route path="about" file="routes-hybrid-files/_public+/about.tsx" />
10      <Route
11        path="contact.jpg"
12        file="routes-hybrid-files/_public+/contact[.jpg].tsx"
13      />
14      <Route index file="routes-hybrid-files/_public+/index.tsx" />
15    </Route>
16    <Route path="project" file="routes-hybrid-files/project+/_layout.tsx">
17      <Route
18        path="parent/child"
19        file="routes-hybrid-files/project+/parent.child/index.tsx"
20      >
21        <Route
22          path="grandchild"
23          file="routes-hybrid-files/project+/parent.child.grandchild/index.tsx"
24        />
25      </Route>
26    </Route>
27    <Route path="users" file="routes-hybrid-files/users+/_layout.tsx">
28      <Route path=":userId" file="routes-hybrid-files/users+/$userId.tsx" />
29      <Route
30        path=":userId/edit"
31        file="routes-hybrid-files/users+/$userId_.edit.tsx"
32      />
33      <Route index file="routes-hybrid-files/users+/index.tsx" />
34    </Route>
35  </Route>
36</Routes>

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

_public.about/route.tsx
_public.contact/route.tsx
_public.privacy/route.tsx

You can name them

_public.about/_about.tsx
_public.contact/_contact.tsx
_public.privacy/_privacy.tsx

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

1npm install -D remix-flat-routes

⚙️ Configuration

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

1const { flatRoutes } = require('remix-flat-routes')
2
3/**
4 * @type {import("@remix-run/dev").AppConfig}
5 */
6module.exports = {
7  // ignore all files in routes folder to prevent
8  // default remix convention from picking up routes
9  ignoredRouteFiles: ['**/*'],
10  routes: async defineRoutes => {
11    return flatRoutes('routes', defineRoutes)
12  },
13}

API

1function flatRoutes(
2  routeDir: string | string[],
3  defineRoutes: DefineRoutesFunction,
4  options: FlatRoutesOptions,
5)
6
7type FlatRoutesOptions = {
8  appDir?: string // optional app directory (defaults to app)
9  basePath?: string // optional base path (default is '/')
10  paramPrefixChar?: string // optional param prefix (default is '$')
11  ignoredRouteFiles?: string[] // optional files to ingore as routes (same as Remix config option)
12  visitFiles?: VisitFilesFunction // optional visitor (useful for tests to provide files without file system)
13}

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)

routes/
  _auth.forgot-password.tsx
  _auth.login.tsx
  _auth.reset-password.tsx
  _auth.signup.tsx
  _auth.tsx
  _landing.about.tsx
  _landing.index.tsx
  _landing.tsx
  app.calendar.$day.tsx
  app.calendar.index.tsx
  app.calendar.tsx
  app.projects.$id.tsx
  app.projects.tsx
  app.tsx
  app_.projects.$id.roadmap.tsx
  app_.projects.$id.roadmap[.pdf].tsx

As React Router routes:

1<Routes>
2  <Route element={<Auth />}>
3    <Route path="forgot-password" element={<Forgot />} />
4    <Route path="login" element={<Login />} />
5    <Route path="reset-password" element={<Reset />} />
6    <Route path="signup" element={<Signup />} />
7  </Route>
8  <Route element={<Landing />}>
9    <Route path="about" element={<About />} />
10    <Route index element={<Index />} />
11  </Route>
12  <Route path="app" element={<App />}>
13    <Route path="calendar" element={<Calendar />}>
14      <Route path=":day" element={<Day />} />
15      <Route index element={<CalendarIndex />} />
16    </Route>
17    <Route path="projects" element={<Projects />}>
18      <Route path=":id" element={<Project />} />
19    </Route>
20  </Route>
21  <Route path="app/projects/:id/roadmap" element={<Roadmap />} />
22  <Route path="app/projects/:id/roadmap.pdf" />
23</Routes>

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

Conventions

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
about.contact.jsx	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*
about_.company.jsx	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.

Justification

• 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.

Colocation

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)

routes/
  _auth.forgot-password.tsx
  _auth.login.tsx
  _auth.tsx
  _landing.about.tsx
  _landing.index.tsx
  _landing.tsx
  app.projects.tsx
  app.projects.$id.tsx
  app.tsx
  app_.projects.$id.roadmap.tsx

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

routes/
  _auth/
    index.tsx x <- route file (same as _auth.tsx)
  _auth.forgot-password/
    index.tsx  <- route file (same as _auth.forgot-password.tsx)
  _auth.login/
    index.tsx   <- route files (same as _auth.login.tsx)
  _landing.about/
    index.tsx   <- route file (same as _landing.about.tsx)
    employee-profile-card.tsx
    get-employee-data.server.tsx
    team-photo.jpg
  _landing.index/
    index.tsx   <- route file (same as _landing.index.tsx)
    scroll-experience.tsx
  _landing/
    index.tsx   <- route file (same as _landing.tsx)
    header.tsx
    footer.tsx
  app/
    index.tsx   <- route file (same as app.tsx)
    primary-nav.tsx
    footer.tsx
  app_.projects.$id.roadmap/
    index.tsx   <- route file (same as app_.projects.$id.roadmap.tsx)
    chart.tsx
    update-timeline.server.tsx
  app.projects/
    index.tsx <- layout file (sames as app.projects.tsx)
    project-card.tsx
    get-projects.server.tsx
    project-buttons.tsx
  app.projects.$id/
    index.tsx  <- route file (sames as app.projects.$id.tsx)

Aliases

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:

1npx migrate-flat-routes <sourceDir> <targetDir> [options]
2
3Example:
4  npx migrate-flat-routes ./app/routes ./app/flatroutes --convention=flat-folders
5
6NOTE:
7  sourceDir and targetDir are relative to project root
8
9Options:
10  --convention=<convention>
11    The convention to use when migrating.
12      flat-files - Migrates to flat files
13      flat-folders - Migrates to flat directories with route.tsx files
14      hybrid - Keep folder structure with '+' suffix and _layout files
15  --force
16    Overwrite target directory if it exists

😍 Contributors

Thanks goes to these wonderful people (emoji key):

Kiliman 💻 📖	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!