Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 39 ยท Routes and Nested Layouts

Routes and Route Modules

Learn how routes.ts maps URLs to route modules in React Router v7 framework mode, with route(), index(), layout() and prefix(), plus what a route module can export.

In framework mode, a route is a pair: a URL pattern and a route module, the file that handles it. The pairs live in one configuration file, app/routes.ts. Because the config is plain TypeScript, you can read the whole URL structure of an app in one place, generate routes from code, or use a file-name convention that builds the list for you (see the flat routes convention).

This lesson covers the configuration helpers, what a route module can export, and how the router picks a route for a URL.

routes.ts

TypeScript
// app/routes.ts  (real React Router v7, read-only)
import {
  type RouteConfig,
  index,
  route,
  layout,
  prefix,
} from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("about", "routes/about.tsx"),

  layout("routes/marketing-layout.tsx", [
    route("pricing", "routes/pricing.tsx"),
    route("contact", "routes/contact.tsx"),
  ]),

  ...prefix("blog", [
    index("routes/blog/index.tsx"),
    route(":slug", "routes/blog/post.tsx"),
  ]),

  route("dashboard", "routes/dashboard/layout.tsx", [
    index("routes/dashboard/overview.tsx"),
    route("settings", "routes/dashboard/settings.tsx"),
  ]),
] satisfies RouteConfig;

The helpers:

Helper Meaning
index(file) the route that renders at the parent's exact URL (no extra segment)
route(path, file, children?) a URL segment (or several, "a/b") plus a module; children render inside it
layout(file, children) a wrapper that adds UI but no URL segment
prefix(path, routes) adds a URL prefix to a list of routes without a wrapper module

The default export is an array, and satisfies RouteConfig checks the shape without widening the type. Paths in the file arguments are relative to app/.

The four route helpers

index() Parent's exact URL
route() Adds a URL segment
layout() Wrapper, no URL
prefix() Shared URL start

Nesting a route inside another means nested UI too.

1 / 2

Stand-in: the route config helpers

The real helpers return plain objects that the framework later reads. This stand-in rebuilds them and then flattens the tree into a table of full URLs, so you can check what a config produces. Try adding a route and see where it lands.

JS Stand-in: index, route, layout and prefix

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

No output.

The marketing-layout.tsx module appears in front of /pricing and /contact but adds nothing to their URLs, and dashboard/layout.tsx wraps both dashboard pages. The prefix helper only changes URLs.

A route module

Each file exports some mix of these (all optional except usually a default component):

Export Runs on Purpose
default server + browser the page component
loader server data for GET requests
action server handles non-GET form posts
clientLoader / clientAction browser the same, but in the browser
ErrorBoundary server + browser UI when this route or its children throw
HydrateFallback server + browser UI while a clientLoader runs on first load
meta server + browser <title> and <meta> tags
links server + browser <link> tags (stylesheets, preloads)
headers server HTTP headers of the document response
handle server + browser any data you want to attach (breadcrumbs, for example)
shouldRevalidate browser decide whether to reload this route's data

Here is a small complete module:

TSX
// app/routes/about.tsx  (real, read-only)
import type { Route } from "./+types/about";

export function meta({}: Route.MetaArgs) {
  return [
    { title: "About us | Shop" },
    { name: "description", content: "Who we are and what we sell." },
  ];
}

export default function About() {
  return (
    <main>
      <h1>About us</h1>
      <p>We sell keyboards.</p>
    </main>
  );
}

Modules are split by the compiler: the server gets loader and action, the browser gets the component. Each route becomes its own chunk, so visiting /about never downloads the dashboard code. That is automatic code splitting.

Choosing a route

The router follows two rules:

  1. Static segments beat dynamic ones. /products/new beats /products/:id.
  2. Longer matches beat shorter ones, and the order in routes.ts is only a tie-breaker.

You can check this with another stand-in: a ranking matcher. Static segments score higher than params, and splats score lowest.

JS Stand-in: ranking route patterns

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

No output.

Notice /products/new picks the static pattern even though /products/:id could also match, and /products/42/reviews falls through to the splat. These rules are the same ones the React Router matcher uses.

Splitting a config

Real apps grow large, so routes.ts is often split across files and built with ordinary code. Because it is just a module that runs at build time, you can loop over a list, import smaller arrays, or even read the file system. Keep it deterministic: it must produce the same list every time it runs.

Common mistakes

  • Forgetting index(): a parent with children and no index renders only its layout at its own URL.
  • Using a leading slash in a child route("/x", ...): write route("x", ...).
  • Putting route files outside app/ or not exporting a default component from a UI route.
  • Relying on route order instead of specificity.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which helper adds a wrapper component without adding a URL segment?

    layout() nests routes inside a module but does not change their URLs.
  2. 2. Which pattern wins for the URL /products/new?

    Static segments rank higher than dynamic ones, so the static /products/new wins regardless of order.
  3. 3. What does a route module's loader export run as?

    Loaders are removed from the browser bundle and run on the server for GET data requests.
  4. 4. What is the purpose of prefix()?

    prefix('blog', [...]) makes /blog and /blog/:slug without creating a layout component.

Summary

  • app/routes.ts maps URLs to route modules with index, route, layout and prefix.
  • A route module exports a component plus optional loader, action, error boundary, meta, links, headers and more.
  • Static segments outrank params and splats; each route is a separate code-split chunk.
  • The next lessons add nesting, params and file-name based routes.

Next: Nested Routes and Layouts