Site icon JD Bots

TanStack Start Project Structure Explained

A new TanStack Start app has sixteen files, and you work in only a few of them. This guide goes through every file and folder the TanStack CLI creates, says what each one does, and shows where your own code goes.

The project here is the one from TanStack Start Tutorial — Part 2, created with the TanStack CLI and its Biome and Netlify options. A project created with other options has the same core files.

Prerequisites

The Whole Project at a Glance

This is everything the CLI writes, apart from node_modules, the folder where npm keeps the installed packages:

bookshop/
├── .cta.json
├── .gitignore
├── .vscode/
│   └── settings.json
├── README.md
├── biome.json
├── netlify.toml
├── package-lock.json
├── package.json
├── src/
│   ├── routeTree.gen.ts
│   ├── router.tsx
│   ├── routes/
│   │   ├── __root.tsx
│   │   └── index.tsx
│   └── styles.css
├── tsconfig.json
├── tsr.config.json
└── vite.config.ts
TanStack’s own quick start describes the same layout.

The Files You Edit

File or folderWhat it’s for
src/routes/Your pages. Each file is a route, and its file name sets the address: index.tsx is the home page at /.
src/routes/__root.tsxThe root route. It wraps every page with the HTML document, its <head> and the global styles, and it always runs.
src/styles.cssStyles for every page. It loads Tailwind CSS.
src/router.tsxCreates the router and its settings, such as scroll restoration and when to preload pages.

The File TanStack Start Writes for You

src/routeTree.gen.ts is the list of your routes. TanStack Start writes it again whenever you run the app, so changes you make to it are lost. The project’s .vscode/settings.json marks it as read-only for that reason.

Settings Files

FileWhat it’s for
package.jsonThe app’s packages and its scripts: dev, build, preview, format, lint and check.
package-lock.jsonThe exact version of every installed package, so every install gets the same ones. npm writes it.
vite.config.tsSettings for Vite, the tool that runs and builds the app, and its plugins: TanStack Start, React, Tailwind CSS, Netlify and the devtools.
tsconfig.jsonSettings for TypeScript, including the #/ path alias for the src folder.
tsr.config.jsonSettings for TanStack Router’s file-based routing. The CLI sets only "target": "react".
biome.jsonSettings for Biome, which formats and checks your code.
netlify.tomlSettings Netlify uses to build and serve the site.
.cta.jsonThe answers you gave the TanStack CLI, such as the add-ons you chose.
.vscode/settings.jsonEditor settings for Visual Studio Code: Biome as the formatter, and routeTree.gen.ts as read-only.
.gitignoreFiles git leaves out, such as node_modules, dist and .env.
README.mdNotes from the template on running, styling and adding routes.

Folders That Appear Later

FolderWhen it appears
node_modules/After npm installs the packages.
dist/After npm run build. It holds the built app.
.netlify/After the first dev run or build. The Netlify plugin adds it to .gitignore.
.tanstack/After the first run or build. It’s listed in .gitignore.

You never edit these, and git leaves all four out.

Where Your Own Code Goes

New pages go in src/routes: a file named about.tsx becomes the page at /about. Changes that every page needs, such as the site title, go in src/routes/__root.tsx.

Common Mistakes

MistakeWhat happensDo this instead
Editing src/routeTree.gen.tsTanStack Start writes over your changesChange the files in src/routes
Committing node_modules or distThe repository fills with files npm and Vite can rebuildLeave them to .gitignore

FAQ

Why do some file names start with two underscores? __root.tsx must have exactly that name: TanStack Start looks for it to find the root route.

Where is index.html? There isn’t one. The root route builds the HTML document, from <html> to <body>.

Conclusion

In a new TanStack Start app, your pages live in src/routes, the page around them is __root.tsx, and routeTree.gen.ts is written for you. The rest are settings files for Vite, TypeScript, Biome and Netlify.

Additional Resources

Related

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

Exit mobile version