Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 39 ยท Routes and Nested Layouts

The Flat Routes Convention: File-Based Routing

Learn the flat routes file-naming convention in React Router v7: dots for nesting, $ for params, _index, pathless layouts, trailing underscores and escapes, with a runnable stand-in.

Writing routes.ts by hand is explicit and flexible. Many teams prefer the opposite: put a file in the routes folder, and the file name is the URL. Remix v2 made this popular with the "flat routes" convention, and React Router v7 keeps it in the @react-router/fs-routes package. You can even mix both: use flatRoutes() for most pages and add a few hand-written routes next to it.

The convention looks cryptic at first (dots, dollar signs, underscores), but it has only a handful of rules. Once you know them, the file list in your editor reads like a site map.

Turning it on

TypeScript
// app/routes.ts  (real, read-only)
import { type RouteConfig } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";

export default flatRoutes() satisfies RouteConfig;

// or mix with manual routes:
// export default [
//   route("health", "health.tsx"),
//   ...(await flatRoutes()),
// ] satisfies RouteConfig;

Install it with npm i -D @react-router/fs-routes. The package reads every file in app/routes/ and returns the same kind of config the helpers produce.

The rules

File name URL Meaning
_index.tsx / the index route of the root
about.tsx /about a normal route
blog.tsx /blog also a layout for every blog.* file (renders an <Outlet />)
blog._index.tsx /blog the index inside the blog layout
blog.$slug.tsx /blog/:slug a dynamic segment: $name becomes :name
blog_.$slug.edit.tsx /blog/:slug/edit trailing _ on a segment: URL kept, but not nested in blog.tsx
_auth.tsx none a pathless layout (leading _)
_auth.login.tsx /login child of _auth, no auth in the URL
($lang).docs.tsx /:lang?/docs parentheses make a segment optional
files.$.tsx /files/* a lone $ is a splat
sitemap[.]xml.tsx /sitemap.xml brackets escape a literal dot
blog.$slug/route.tsx /blog/:slug a folder with route.tsx lets you keep helper files next to a route

Two ideas explain most of the table:

  1. A dot is a slash, and nesting follows the names. If a file called blog.tsx exists, then blog.$slug.tsx renders inside it. The parent is the longest other route name that is a prefix.
  2. A leading underscore on a segment hides it from the URL, and a trailing underscore opts a file out of the parent's layout while keeping its URL.

Reading file names

. Slash and nesting
$id Dynamic param
_name Pathless layout
name_ Escape the parent layout

([lang]) optional, [.] literal dot, $ alone is a splat.

1 / 2

Stand-in: a flat-routes interpreter

The real package is more complete, but the heart of it fits on one screen. This stand-in takes file names and prints the URL and the parent layout of each. Add your own file names to test your understanding.

JS Stand-in: file names to URLs and parents

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check the results against the table. blog_.$slug.edit has no parent even though blog exists, because blog_ is a different name. _auth.login becomes /login with _auth as its layout. The real implementation also handles folders, ignores files starting with a dot, and warns about duplicate URLs.

A realistic folder

TEXT
app/routes/
  _index.tsx                  /
  _auth.tsx                   (centered card layout, no URL)
  _auth.login.tsx             /login
  _auth.register.tsx          /register
  products.tsx                /products   (layout with filters)
  products._index.tsx         /products   (the list)
  products.$id.tsx            /products/:id
  products_.new.tsx           /products/new (full page, no filter layout)
  account.tsx                 /account   (layout)
  account.settings.tsx        /account/settings
  $.tsx                       /*          (catch-all 404)

Notice that products.new.tsx would render inside the products layout, while products_.new.tsx renders in the root only. Use the trailing underscore when a page needs the full width.

Flat files versus routes.ts

flatRoutes() hand-written routes.ts
Finding a file from a URL search the name read the config
Nested folders one flat folder, long names any structure
Special cases escape syntax to learn plain code
Refactors rename files edit one file

Both produce the same route modules and behave the same at runtime. A good rule is to choose per project, document it in the README, and do not switch halfway without a plan. The file-based routes lesson in the router tutorial shows the same convention from the router's point of view.

Common mistakes

  • Expecting blog.new.tsx to escape the blog layout. Use blog_.new.tsx.
  • Forgetting <Outlet /> in blog.tsx, which silently hides every child.
  • Two files producing the same URL (for example about.tsx and about._index.tsx); the second wins or an error appears.
  • Naming a file with a literal dot, such as sitemap.xml.tsx, without brackets: that means /sitemap/xml.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file creates the URL /blog/:slug?

    A dot is a slash, and a dollar sign starts a dynamic segment.
  2. 2. What does a leading underscore in _auth.login.tsx do?

    Leading underscore creates a pathless layout; the URL is just /login.
  3. 3. How do you make /blog/:slug/edit skip the blog.tsx layout but keep its URL?

    A trailing underscore on blog opts out of nesting under blog.tsx.
  4. 4. Which file name creates the URL /sitemap.xml?

    Brackets escape the dot, so it stays part of the segment instead of meaning a slash.

Summary

  • flatRoutes() from @react-router/fs-routes builds the route config from file names.
  • Dots are slashes and nesting, $ is a param, a lone $ is a splat, () is optional, [] escapes.
  • Leading underscore means pathless layout; trailing underscore opts out of the parent layout.
  • You can combine file-based routes with hand-written ones.

Next: Links, Navigation and Meta