File Route Conventions

The @react-router/fs-routes package enables file-convention based route config.

Setting up

First install the @react-router/fs-routes package:

npm i @react-router/fs-routes

Then use it to provide route config in your app/routes.ts file:

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

export default flatRoutes() satisfies RouteConfig;

This will look for routes in the app/routes directory by default, but this can be configured via the rootDirectory option which is relative to your app directory:

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

export default flatRoutes({
  rootDirectory: "file-routes",
}) satisfies RouteConfig;

The rest of this guide will assume you're using the default app/routes directory.

Basic Routes

Any modules in the app/routes directory will become routes in your application. The filename maps to the route's URL pathname, except for _index.tsx which is the index route for the root route. You can use .js, .jsx, .ts or .tsx file extensions.

app/
├── routes/
│   ├── _index.tsx
│   └── about.tsx
└── root.tsx

Note that these routes will be rendered in the outlet of app/root.tsx because of nested routing.

Dot Delimiters

Adding a . to a route filename will create a / in the URL.

 app/
├── routes/
│   ├── _index.tsx
│   ├── about.tsx
│   ├── concerts.trending.tsx
│   ├── concerts.salt-lake-city.tsx
│   └── concerts.san-diego.tsx
└── root.tsx

The dot delimiter also creates nesting, see the nesting section for more information.

Dynamic Segments

Usually your URLs aren't static but data-driven. Dynamic segments allow you to match segments of the URL and use that value in your code. You create them with the $ prefix.

 app/
├── routes/
│   ├── _index.tsx
│   ├── about.tsx
│   ├── concerts.$city.tsx
│   └── concerts.trending.tsx
└── root.tsx

The value will be parsed from the URL and pass it to various APIs. We call these values "URL Parameters". The most useful places to access the URL params are in loaders and actions.

export async function serverLoader({ params }) {
  return fakeDb.getAllConcertsForCity(params.city);
}

You'll note the property name on the params object maps directly to the name of your file: $city.tsx becomes params.city.

Routes can have multiple dynamic segments, like concerts.$city.$date, both are accessed on the params object by name:

export async function serverLoader({ params }) {
  return fake.db.getConcerts({
    date: params.date,
    city: params.city,
  });
}

See the routing guide for more information.

Nested Routes

Nested Routing is the general idea of coupling segments of the URL to component hierarchy and data. You can read more about it in the Routing Guide.

You create nested routes with dot delimiters. If the filename before the . matches another route filename, it automatically becomes a child route to the matching parent. Consider these routes:

 app/
├── routes/
│   ├── _index.tsx
│   ├── about.tsx
│   ├── concerts._index.tsx
│   ├── concerts.$city.tsx
│   ├── concerts.trending.tsx
│   └── concerts.tsx
└── root.tsx

All the routes that start with app/routes/concerts. will be child routes of app/routes/concerts.tsx and render inside the parent route's outlet.

Note you typically want to add an index route when you add nested routes so that something renders inside the parent's outlet when users visit the parent URL directly.

For example, if the URL is /concerts/salt-lake-city then the UI hierarchy will look like this:

<Root>
  <Concerts>
    <City />
  </Concerts>
</Root>

Nested URLs without Layout Nesting

Sometimes you want the URL to be nested, but you don't want the automatic layout nesting. You can opt out of nesting with a trailing underscore on the parent segment:

 app/
├── routes/
│   ├── _index.tsx
│   ├── about.tsx
│   ├── concerts.$city.tsx
│   ├── concerts.trending.tsx
│   ├── concerts.tsx
│   └── concerts_.mine.tsx
└── root.tsx

Note that /concerts/mine does not nest with app/routes/concerts.tsx anymore, but app/root.tsx. The trailing_ underscore creates a path segment, but it does not create layout nesting.

Think of the trailing_ underscore as the long bit at the end of your parent's signature, writing you out of the will, removing the segment that follows from the layout nesting.

Nested Layouts without Nested URLs

We call these Pathless Routes

Sometimes you want to share a layout with a group of routes without adding any path segments to the URL. A common example is a set of authentication routes that have a different header/footer than the public pages or the logged in app experience. You can do this with a _leading underscore.

 app/
├── routes/
│   ├── _auth.login.tsx
│   ├── _auth.register.tsx
│   ├── _auth.tsx
│   ├── _index.tsx
│   ├── concerts.$city.tsx
│   └── concerts.tsx
└── root.tsx

Think of the _leading underscore as a blanket you're pulling over the filename, hiding the filename from the URL.

Optional Segments

Wrapping a route segment in parentheses will make the segment optional.

 app/
├── routes/
│   ├── ($lang)._index.tsx
│   ├── ($lang).$productId.tsx
│   └── ($lang).categories.tsx
└── root.tsx

You may wonder why /american-flag-speedo is matching the ($lang)._index.tsx route instead of ($lang).$productId.tsx. This is because when you have an optional dynamic param segment followed by another dynamic param, it cannot reliably be determined if a single-segment URL such as /american-flag-speedo should match /:lang /:productId. Optional segments match eagerly and thus it will match /:lang. If you have this type of setup it's recommended to look at params.lang in the ($lang)._index.tsx loader and redirect to /:lang/american-flag-speedo for the current/default language if params.lang is not a valid language code.

Splat Routes

While dynamic segments match a single path segment (the stuff between two / in a URL), a splat route will match the rest of a URL, including the slashes.

 app/
├── routes/
│   ├── _index.tsx
│   ├── $.tsx
│   ├── about.tsx
│   └── files.$.tsx
└── root.tsx

Similar to dynamic route parameters, you can access the value of the matched path on the splat route's params with the "*" key.

export async function serverLoader({ params }) {
  const filePath = params["*"];
  return fake.getFileInfo(filePath);
}

Escaping Special Characters

If you want one of the special characters used for these route conventions to actually be a part of the URL, you can escape the conventions with [] characters. This can be especially helpful for resource routes that include an extension in the URL.

Folders for Organization

Routes can also be folders with a route.tsx file inside defining the route module. The rest of the files in the folder will not become routes. This allows you to organize your code closer to the routes that use them instead of repeating the feature names across other folders.

The files inside a folder have no meaning for the route paths, the route path is completely defined by the folder name.

Consider these routes:

 app/
├── routes/
│   ├── _landing._index.tsx
│   ├── _landing.about.tsx
│   ├── _landing.tsx
│   ├── app._index.tsx
│   ├── app.projects.tsx
│   ├── app.tsx
│   └── app_.projects.$id.roadmap.tsx
└── root.tsx

Some, or all of them can be folders holding their own route module inside.

app/
├── routes/
│   ├── _landing._index/
│   │   ├── route.tsx
│   │   └── scroll-experience.tsx
│   ├── _landing.about/
│   │   ├── employee-profile-card.tsx
│   │   ├── get-employee-data.server.ts
│   │   ├── route.tsx
│   │   └── team-photo.jpg
│   ├── _landing/
│   │   ├── footer.tsx
│   │   ├── header.tsx
│   │   └── route.tsx
│   ├── app._index/
│   │   ├── route.tsx
│   │   └── stats.tsx
│   ├── app.projects/
│   │   ├── get-projects.server.ts
│   │   ├── project-buttons.tsx
│   │   ├── project-card.tsx
│   │   └── route.tsx
│   ├── app/
│   │   ├── footer.tsx
│   │   ├── primary-nav.tsx
│   │   └── route.tsx
│   ├── app_.projects.$id.roadmap/
│   │   ├── chart.tsx
│   │   ├── route.tsx
│   │   └── update-timeline.server.ts
│   └── contact-us.tsx
└── root.tsx

Note that when you turn a route module into a folder, the route module becomes folder/route.tsx, all other modules in the folder will not become routes. For example:

# these are the same route:
app/routes/app.tsx
app/routes/app/route.tsx

# as are these
app/routes/app._index.tsx
app/routes/app._index/route.tsx