Define routes

In this chapter we will learn about the basics of the file-system based router. We will learn how to define routes, how to use parameters and page layouts.

The router can be configured by creating a react-server.config.mjs or react-server.config.json file in the root of your project. The configuration file should export a configuration object and it should include the root path for your routes. You can also specify a public path for your static files. The file-system based router will automatically scaffold the files in the root directory to prepare and build the routing based on your files in the root directory.

export default {
  root: "src/pages",
  public: "public",
};

Your directories and files specify the routes your application will use. There are built-in conventions in the router which translates the names of directories and files to route paths and route parameters. To create a new route you need to create a file in the root directory.

Route files have to export default a React Server Component which will be used to render the route.

export default function Home() {
  return <h1>Home</h1>;
}

If you name your file index or page it will be treated as an index route. Index routes are the default routes for directories. For example if you create a file named index.jsx in the root directory it will be treated as the default route for your application. If you create a file named index.jsx in a directory named about it will be treated as the default route for the about directory.

If you name your file anything other than index or page it will be treated as a named route. For example if you create a file named about.jsx in the root directory it will be treated as a named route with the path /about. If you create a file named about.jsx in a directory named users it will be treated as a named route with the path /users/about.

You can create nested routes by creating directories in the root directory. For example if you create a directory named users in the root directory and create a file named index.jsx in the users directory it will be treated as a nested route with the path /users. If you create a file named about.jsx in the users directory it will be treated as a nested route with the path /users/about.

You can create route parameters by adding a parameter name in brackets to the name of the file. For example if you create a file named [id].jsx in the root directory it will be treated as a named route with the path /[id]. If you create a file named [id].jsx in a directory named users it will be treated as a named route with the path /users/[id]. You can also create nested route parameters by creating nested directories. For example if you create a directory named users in the root directory and create a file named [id].jsx in the users directory it will be treated as a nested route with the path /users/[id]. You will be able to access the route parameter in your component as React props.

export default function User({ id }) {
  return <h1>User #{id}</h1>;
}

You can also use multiple route parameters in a single route segment. For example if you create a file named [id]-[name].jsx it will be treated as a route with the path pattern of /[id]-[name] and you will receive both id and name as props in your component.

export default function User({ id, name }) {
  return <h1>User #{id} - {name}</h1>;
}

You can create route parameters for multiple segments by adding a parameter name in brackets to the name of the file. For example if you create a file named [...id].jsx in the root directory it will be treated as a named route with the path /[...id]. If you create a file named [...id].jsx in a directory named users it will be treated as a named route with the path /users/[...id]. You can also create nested route parameters by creating nested directories. For example if you create a directory named users in the root directory and create a file named [...id].jsx in the users directory it will be treated as a nested route with the path /users/[...id].

The parameter at runtime will be an array of strings. You will be able to access the route parameter in your component as a React prop.

// /[...slug].page.jsx
export default function Page({ slug }) {
  return <h1>/{slug.join("/")}</h1>;
}

You can create route parameters for optional segments by adding a parameter name in brackets to the name of the file. For example if you create a file named [[...id]].jsx in the root directory it will be treated as a named route with the path /[[...id]]. If you create a file named [[...id]].jsx in a directory named users it will be treated as a named route with the path /users/[[...id]]. You can also create nested route parameters by creating nested directories. For example if you create a directory named users in the root directory and create a file named [[...id]].jsx in the users directory it will be treated as a nested route with the path /users/[[...id]].

Omit: you can omit any part of the directory or file name by wrapping the part in parentheses. For example if you create a file named (404).[[...slug]].page.mdx in the root directory it will be treated as a route with the path /[[...slug]]. You can use this to extend the directory/file name with additional information without affecting the route path.

You can create layouts by creating a file including layout.jsx in the file name. The layout file will be used to wrap all the routes in the same directory where the layout file is. You can also create nested layouts by creating a file named layout.jsx in a sub-directory. You can also use omitted parts in the layout file name. For example if you create a file named (root).layout.jsx in the root directory it will be used as the layout for all the routes in the root directory.

Your layout component will receive a children prop which you need to use to render your route components.

export default function Layout({ children }) {
  return (
    <>
      <h1>Layout</h1>
      {children}
    </>
  );
}

Transparent segments are segments that are not rendered in the URL but are used to identify your file for yourself. You can create transparent segments by creating a file named (transparent).page.jsx where (transparent) is the name of your transparent segment and could be anything you want. For example if you create a file named (main).page.jsx in the root directory it will be treated as a route with the path /. If you create a file named (main).page.jsx in a directory named users it will be treated as a route with the path /users. You can also use transparent segments in your directory structure to group your files. For example if you create a file named page.jsx in a directory named (dashboard)/users it will be treated as a route with the path /users.

src
- (root).layout.jsx
- (root).page.jsx
- (dashboard)
  - users
    - (users).page.jsx
    - [userId].page.jsx

You can escape route segments by wrapping the segment in curly braces. For example if you create a file named {sitemap.xml}.server.mjs in the root directory it will be treated as a named route with the path /sitemap.xml.

Example: see the Photos example in the examples directory for a basic example of file-system based routing.