File-Based Routing

Most of the TanStack Router documentation is written for file-based routing and is intended to help you understand in more detail how to configure file-based routing and the technical details behind how it works. While file-based routing is the preferred and recommended way to configure TanStack Router, you can also use code-based routing if you prefer.

File-based routing is a way to configure your routes using the filesystem. Instead of defining your route structure via code, you can define your routes using a series of files and directories that represent the route hierarchy of your application. This brings a number of benefits:

• Simplicity: File-based routing is visually intuitive and easy to understand for both new and experienced developers.
• Organization: Routes are organized in a way that mirrors the URL structure of your application.
• Scalability: As your application grows, file-based routing makes it easy to add new routes and maintain existing ones.
• Code-Splitting: File-based routing allows TanStack Router to automatically code-split your routes for better performance.
• Type-Safety: File-based routing raises the ceiling on type-safety by generating managing type linkages for your routes, which can otherwise be a tedious process via code-based routing.
• Consistency: File-based routing enforces a consistent structure for your routes, making it easier to maintain and update your application and move from one project to another.

While directories have long been used to represent route hierarchy, file-based routing introduces an additional concept of using the . character in the file-name to denote a route nesting. This allows you to avoid creating directories for few deeply nested routes and continue to use directories for wider route hierarchies. Let's take a look at some examples!

Directories can be used to denote route hierarchy, which can be useful for organizing multiple routes into logical groups and also cutting down on the filename length for large groups of deeply nested routes.

See the example below:

Flat routing gives you the ability to use .s to denote route nesting levels.

This can be useful when you have a large number of uniquely deeply nested routes and want to avoid creating directories for each one:

See the example below:

It's extremely likely that a 100% directory or flat route structure won't be the best fit for your project, which is why TanStack Router allows you to mix both flat and directory routes together to create a route tree that uses the best of both worlds where it makes sense:

See the example below:

Both flat and directory routes can be mixed together to create a route tree that uses the best of both worlds where it makes sense.

To get started with file-based routing, you'll need to configure your project's bundler to use the TanStack Router Plugin or the TanStack Router CLI.

To enable file-based routing, you'll need to be using React with a supported bundler. See if your bundler is listed in the configuration guides below.

• Installation with Vite
• Installation with Rspack/Rsbuild
• Installation with Webpack
• Installation with Esbuild

When using TanStack Router's file-based routing through one of the supported bundlers, our plugin will automatically generate your route configuration through your bundler's dev and build processes. It is the easiest way to use TanStack Router's route generation features.

If your bundler is not yet supported, you can reach out to us on Discord or GitHub to let us know. Till then, fear not! You can still use the @tanstack/router-cli package to generate your route tree file.