Skip to main content
0 reactions

TanStack Start Route File Naming Conventions Explained

Card titled Route File Naming Conventions, showing four files in src/routes pointing to their addresses: books/$bookId.tsx to /books/1, _shop/cart.tsx to /cart, (info)/contact.tsx to /contact and sitemap[.]xml.tsx to /sitemap.xml.
TanStack Start route file naming conventions.

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

RuleWhat it doesExample fileAddress
__root.tsxThe root route, which wraps every page. It must sit at the top of src/routes.__root.tsxnone
indexThe page at its folder’s own addressbooks/index.tsx/books
A folderAdds the folder’s name to the addressaccount/orders.tsx/account/orders
. (a dot)Works like a folder, inside one file nameauthors.$authorId.tsx/authors/$authorId
$A dynamic part that matches any valuebooks/$bookId.tsx/books/1, /books/2 and so on
_ at the startA layout with no address of its own. The pages inside it keep their own addresses._shop.tsx and _shop/cart.tsx/cart
_ at the endTakes a page out of its parent’s layout, while keeping the addressaccount_.help.tsx/account/help
- at the startLeft out of the routes, for files that aren’t pagesbooks/-components/book-card.tsxnone
(name) folderGroups files without adding to the address(info)/contact.tsx/contact
[ ]Keeps a character that has a meaning, such as a dot, as plain textsitemap[.]xml.tsx/sitemap.xml
route.tsxThe layout file for a folder’s own addressaccount/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/routesPlain text
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:

src/routes/books/-components/book-card.tsxTypeScript
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:

src/routeTree.gen.ts (excerpt)TypeScript
  to:
    | '/'
    | '/about'
    | '/sitemap.xml'
    | '/contact'
    | '/cart'
    | '/account/orders'
    | '/account/help'
    | '/authors/$authorId'
    | '/books/$bookId'
    | '/account'
    | '/books'

What the list shows:

  • /cart and /contact have no _shop or (info) in them: a _ layout and a ( ) group never add to the address.
  • /sitemap.xml keeps its dot, thanks to the square brackets.
  • /authors/$authorId and /books/$bookId end 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.tsx isn’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:

src/routeTree.gen.ts (excerpt)TypeScript
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

MistakeWhat happensDo 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 addressThe page isn’t at /info/contactOpen it at /contact
Editing src/routeTree.gen.tsTanStack Start writes over your changesRename 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

TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.

0 comments