File Naming Conventions

File-based routing requires that you follow a few simple file naming conventions to ensure that your routes are generated correctly. The concepts these conventions enable are covered in detail in the Route Trees & Nesting guide.

Important

Routes starting with /api are reserved and cannot not be used for file-based routing. These routes are reserved for future use by the TanStack Start for API routes. If you need to use routes starting with /api when using TanStack Router with file-based routing, then you'll need to configure the apiBase option to a different value.

Feature	Description
__root.tsx	The root route file must be named __root.tsx and must be placed in the root of the configured routesDirectory.
. Separator	Routes can use the . character to denote a nested route. For example, blog.post will be generated as a child of blog.
$ Token	Route segments with the $ token are parameterized and will extract the value from the URL pathname as a route param.
_ Prefix	Route segments with the _ prefix are considered to be pathless routes and will not be used when matching its child routes against the URL pathname.
_ Suffix	Route segments with the _ suffix exclude the route from being nested under any parent routes.
(folder) folder name pattern	A folder that matches this pattern is treated as a route group, preventing the folder from being included in the route's URL path.
index Token	Route segments ending with the index token (before any file extensions) will match the parent route when the URL pathname matches the parent route exactly. This can be configured via the indexToken configuration option, see options.
.route.tsx File Type	When using directories to organise routes, the route suffix can be used to create a route file at the directory's path. For example, blog.post.route.tsx or blog/post/route.tsx can be used as the route file for the /blog/post route. This can be configured via the routeToken configuration option, see options.

💡 Remember: The file-naming conventions for your project could be affected by what options are configured.

Dynamic Path Params

Dynamic path params can be used in both flat and directory routes to create routes that can match a dynamic segment of the URL path. Dynamic path params are denoted by the $ character in the filename:

Filename	Route Path	Component Output
...	...	...
ʦ posts.$postId.tsx	/posts/$postId	<Root><Posts><Post>

We'll learn more about dynamic path params in the Path Params guide.

Pathless Routes

Pathless routes wrap child routes with either logic or a component without requiring a URL path. Non-path routes are denoted by the _ character in the filename:

Filename	Route Path	Component Output
ʦ _app.tsx
ʦ _app.a.tsx	/a	<Root><App><A>
ʦ _app.b.tsx	/b	<Root><App><B>

To learn more about pathless routes, see the Routing Concepts - Pathless Routes guide.

File Naming Conventions

Dynamic Path Params

Pathless Routes

Subscribe to Bytes

Subscribe to Bytes