In TanStack Start, the name of a file in src/routes decides the address of its page. That’s file-based routing, and it follows a short list of route file naming conventions: index, folders and dots, $, _, -, ( ) and [ ].
This post explains each rule in plain words, then shows the addresses TanStack Start made from a real set of files.
The Naming Rules
| Rule | What it does | Example file | Address |
|---|---|---|---|
__root.tsx | The root route, which wraps every page. It must sit at the top of src/routes. | __root.tsx | none |
index | The page at its folder’s own address | books/index.tsx | /books |
| A folder | Adds the folder’s name to the address | account/orders.tsx | /account/orders |
. (a dot) | Works like a folder, inside one file name | authors.$authorId.tsx | /authors/$authorId |
$ | A dynamic part that matches any value | books/$bookId.tsx | /books/1, /books/2 and so on |
_ at the start | A layout with no address of its own. The pages inside it keep their own addresses. | _shop.tsx and _shop/cart.tsx | /cart |
_ at the end | Takes a page out of its parent’s layout, while keeping the address | account_.help.tsx | /account/help |
- at the start | Left out of the routes, for files that aren’t pages | books/-components/book-card.tsx | none |
(name) folder | Groups files without adding to the address | (info)/contact.tsx | /contact |
[ ] | Keeps a character that has a meaning, such as a dot, as plain text | sitemap[.]xml.tsx | /sitemap.xml |
route.tsx | The layout file for a folder’s own address | account/route.tsx | /account, around the pages in account |
These rules come from TanStack Router’s file naming conventions (opens in a new tab), which TanStack Start uses as they are.
Try the Rules in Your App
To see the rules at work, start the dev server with npm run dev and create these files in src/routes. Next to the pages the app already had, the folder looks like this:
src/routes/
├── __root.tsx
├── index.tsx
├── about.tsx
├── account_.help.tsx
├── authors.$authorId.tsx
├── sitemap[.]xml.tsx
├── _shop.tsx
├── _shop/
│ └── cart.tsx
├── (info)/
│ └── contact.tsx
├── account/
│ ├── route.tsx
│ ├── index.tsx
│ └── orders.tsx
└── books/
├── index.tsx
├── $bookId.tsx
└── -components/
└── book-card.tsx
TanStack Start fills each new, empty page file with starter code. book-card.tsx isn’t a page, so give it a small component of its own:
export function BookCard({ title }: { title: string }) {
return <p>{title}</p>;
}
Now open src/routeTree.gen.ts, the list of routes TanStack Start writes for you. Its to list holds every address a Link can open:
to:
| '/'
| '/about'
| '/sitemap.xml'
| '/contact'
| '/cart'
| '/account/orders'
| '/account/help'
| '/authors/$authorId'
| '/books/$bookId'
| '/account'
| '/books'
What the list shows:
/cartand/contacthave no_shopor(info)in them: a_layout and a( )group never add to the address./sitemap.xmlkeeps its dot, thanks to the square brackets./authors/$authorIdand/books/$bookIdend in a dynamic part, which matches any value, such as/books/1. Part 4 of the series shows how a page reads it.book-card.tsxisn’t in the list at all.
The same file also records each page’s parent. account/orders.tsx sits inside account/route.tsx, while account_.help.tsx hangs straight off the root route, even though its address starts with /account:
const AccountOrdersRoute = AccountOrdersRouteImport.update({
id: '/orders',
path: '/orders',
getParentRoute: () => AccountRouteRoute,
} as any)
const AccountHelpRoute = AccountHelpRouteImport.update({
id: '/account_/help',
path: '/account/help',
getParentRoute: () => rootRouteImport,
} as any)
Clean Up
Delete the files and folders you created to try the rules, so they don’t stay in your app as pages. TanStack Start updates src/routeTree.gen.ts by itself.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Keeping a component file in src/routes without a - | The dev server warns: Route file "…/src/routes/header.tsx" does not export a Route. This file will not be included in the route tree. | Start the file or folder name with -, such as -components |
| Expecting a group folder in the address | The page isn’t at /info/contact | Open it at /contact |
Editing src/routeTree.gen.ts | TanStack Start writes over your changes | Rename or move the files in src/routes |
FAQ
Should I use folders or dots? Either: books/$bookId.tsx and books.$bookId.tsx make the same address. Pick the style that keeps your folder easy to read, and stay with it.
Can I change the rules? Some of them. The router plugin has options such as routeFileIgnorePrefix (the -), indexToken and routeToken, listed in the file-based routing options (opens in a new tab). The defaults are what most projects use.
Conclusion
A file’s name is its page’s address: index for a folder’s own page, folders or dots for nesting, $ for a value, _ for layouts without an address, ( ) to group files, - to leave a file out and [ ] to keep a special character.
Additional Resources
- File Naming Conventions (opens in a new tab) in the TanStack Router docs
- Routing Concepts (opens in a new tab), with every kind of route
- Route Trees (opens in a new tab)
- File-based routing options (opens in a new tab)
Related
- TanStack Start Tutorial — Part 3: Pages and Links: File-Based Routing
- TanStack Start Tutorial for Beginners, every part of the series
TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.
0 comments