File-system based router

@lazarv/react-server allows you to build your application using a file-system based router too. This router allows you to create a file-system based routing structure, similar to meta-frameworks like Next.js.

@lazarv/react-server will automatically use the file-system based router when you don't specify an entrypoint for your app when using the react-server CLI.

To start your development server using the file-system based router, run the command:

pnpm react-server

Build your application using the file-system based router by using:

pnpm react-server build

Start your built production application as usual by using:

pnpm react-server start

The router supports typed routes out of the box. If you use TypeScript, you can include the generated types in your project and all of your routes will be type checked. Typed routes work for Link components, useMatch hooks, navigate, replace and prefetch functions from the useClient hook and also the possible outlets available to use in a ReactServerComponent.

To include the generated types in your project you only need to include .ts files from the .react-server directory in your TypeScript configuration. To do so, add .react-server/**/*.ts to the include array in your tsconfig.json file:

{
  "compilerOptions": {
    // ...
  },
  "include": [/* ... */, ".react-server/**/*.ts"]
}

The router also generates a virtual @lazarv/react-server/routes module that exports typed route descriptors for every route — with .Link, .href(), .useParams(), typed createPage / createLayout helpers, branded outlet types, and more. See the routes module documentation for details.

For a complete guide on the typed routing system — including the programmatic createRoute / createRouter API, schema validation, lightweight parse functions, typed hooks, functional search updaters, and SearchParams transforms — see the typed router page. For typed routes in the file-system router specifically, see define routes.

The file-system based router is compatible with Next.js in a way that if you don't use any Next.js specific modules to implement your application, you can use the file-system based router interchangeably with your Next.js project.

The file-system based router shares the following features with Next.js:

• Static and dynamic routes
• Layouts and pages
• Nested routes
• Route groups
• Parallel routes
• Error handling
• Loading states

To emulate the Next.js type file-system based router, configure the router to only allow page.tsx files to be used as page routes in the app directory or change the root directory to src/app when you use a src directory based project structure.

{
  "root": "app",
  "page": {
    "include": ["**/page.tsx"]
  }
}