In this part, you create your first TanStack Start app, run it on your own computer and change its home page. One command creates the app, and a few more bring its tools up to date.
This is Part 2 of the TanStack Start Tutorial, a free, hands-on course for complete beginners. The app you start here is the Bookshop, a small website that grows a little in every part.
By the end of this part, you’ll have:
- a TanStack Start app called
bookshopon your computer, with the newest TypeScript and Biome - the app running in your browser at
http://localhost:3000 - your own Bookshop home page in place of the starter page
This is Part 2 of the TanStack Start Tutorial. The parts in Module A, Start Here:
- Part 1: What Is TanStack Start? A Full-Stack React Framework Explained
- Part 2: Create Your First TanStack Start App (you are here)
- Part 3: Pages and Links: File-Based Routing
All parts of the TanStack Start Tutorial
Module A: Start Here
- Part 1: What Is TanStack Start? A Full-Stack React Framework Explained
- Part 2: Create Your First TanStack Start App
- Part 3: Pages and Links: File-Based Routing
Module B: Routing
- Part 4: Dynamic Routes and Path Params
- Part 5: Search Params: Type-Safe Filters and Sorting
- Part 6: Layouts, Nested Routes and Navigation in Code
Module C: Data
- Part 7: Load Data with Route Loaders
- Part 8: Server Functions
- Part 9: Forms and Mutations
- Part 10: TanStack Query with TanStack Start
- Part 11: Streaming and Deferred Data
Module D: Server
- Part 12: What Runs Where: the Execution Model
- Part 13: Environment Variables and Secrets
- Part 14: Server Routes: Build a JSON API
- Part 15: Middleware and Context
- Part 16: Errors and Not Found Pages
Module E: Database
- Part 17: Connect PostgreSQL with Drizzle ORM
- Part 18: Create, Edit and Delete Data
Module F: Sign-In
- Part 19: Sessions and Cookies
- Part 20: Protected Routes
- Part 21: Sign-In with Better Auth: Email and GitHub
Module G: Rendering
- Part 22: Server-Side Rendering and Hydration Errors
- Part 23: Selective SSR and SPA Mode
- Part 24: Static Prerendering and ISR
Module H: Look and SEO
- Part 25: Style with Tailwind CSS
- Part 26: SEO: Titles, Meta Tags, Sitemap and Structured Data
Module I: Ship
- Part 27: Test Your App with Vitest
- Part 28: Production Build and Checklist
- Part 29: Deploy to Netlify for Free with a Neon Database
- Part 30: Final Project, Cheat Sheet and What to Learn Next
Cost: free. Everything in this part runs on your own computer.
Every command and output on this page is real, run with TanStack Start 1 on Node.js 26.
Prerequisites
- Node.js 26, the current long-term support (LTS) release, from the official download page.
- The newest npm. npm, the package manager, comes with Node.js. This part uses npm 12; How to Update npm to the Newest Version shows how to update it.
- A terminal, the app where you type commands, and a code editor such as Visual Studio Code.
Check both versions in your terminal:
node -v
v26.13.1
npm -v
12.2.3
New to TanStack Start? Part 1 explains what it is in a few minutes of reading.
Step 1: Create the App with the TanStack CLI
Open your terminal in the folder where you keep your projects, and run this command. It downloads the TanStack CLI, the official tool that sets up new projects, and creates the app in a new folder called bookshop:
npx @tanstack/cli@latest create bookshop --package-manager npm --toolchain biome --deployment netlify --no-examples --no-intent -y
What each part does:
npx @tanstack/cli@latest create bookshopruns the newest TanStack CLI and creates an app namedbookshop.--package-manager npminstalls the app’s packages with npm.--toolchain biomeadds Biome, a tool that formats your code and checks it for mistakes.--deployment netlifyprepares the app for Netlify, where a later part puts it online for free.--no-examplesleaves out the demo pages, so you start with a clean app.--no-intentleaves out TanStack Intent, extra set-up files for AI coding assistants.-yaccepts the defaults for everything else, so the CLI asks no questions.
The first time, npx asks before it downloads the CLI. Type y and press Enter:
Need to install the following packages:
@tanstack/cli@0.72.16
Ok to proceed? (y) y
The CLI then creates the project, installs its packages and builds it once. When it’s done, the end of the output looks like this:
◇ Route tree generated
│
└ Your TanStack app is ready in 'bookshop'.
Use the following commands to start your app:
% cd bookshop
% npm run dev
Move into the new folder. Run every command in the rest of this part from there:
cd bookshop
Step 2: Update TypeScript, Node.js Types and Biome
The CLI’s template installs TypeScript 6, the type definitions for Node.js 22 and an older Biome. This command moves all of them to their newest releases:
npm install --save-dev @typescript/native@npm:typescript@7 typescript@npm:@typescript/typescript6@6 @types/node@26 @biomejs/biome@2
What each package does:
@typescript/native@npm:typescript@7installs TypeScript 7 under the name@typescript/native. It checks your code, andnpx tscruns it.typescript@npm:@typescript/typescript6@6gives the usual name,typescript, to TypeScript 6’s compatibility package. Some build tools still need TypeScript 6’s programming interface, which TypeScript 7 doesn’t have yet. This side-by-side setup is the one TypeScript 7’s announcement recommends.@types/node@26adds the type definitions for Node.js 26, so your editor knows Node.js’s features.@biomejs/biome@2installs the newest Biome 2.
npm prints this:
npm warn ERESOLVE overriding peer dependency
npm warn While resolving: @typescript-eslint/typescript-estree@8.73.0
npm warn Found: @typescript/native@7.0.2
npm warn node_modules/@typescript/native
npm warn dev @typescript/native@"npm:typescript@7" from the root project
npm warn
npm warn Could not resolve dependency:
npm warn peerOptional @typescript/native@"npm:typescript@>=7.1.0-dev.20261009.1 || >=7.1.0-beta <7.1.0-dev" from @typescript-eslint/typescript-estree@8.73.0
npm warn node_modules/@typescript-eslint/typescript-estree
npm warn @typescript-eslint/typescript-estree@"^8.58.2" from detective-typescript@14.1.2
npm warn node_modules/detective-typescript
npm warn
npm warn Conflicting peer dependency: @typescript/native@7.1.0-dev.20261117.1
npm warn node_modules/@typescript/native
npm warn peerOptional @typescript/native@"npm:typescript@>=7.1.0-dev.20261009.1 || >=7.1.0-beta <7.1.0-dev" from @typescript-eslint/typescript-estree@8.73.0
npm warn node_modules/@typescript-eslint/typescript-estree
npm warn @typescript-eslint/typescript-estree@"^8.58.2" from detective-typescript@14.1.2
npm warn node_modules/detective-typescript
added 3 packages, removed 5 packages, changed 5 packages, and audited 658 packages in 7s
211 packages are looking for funding
run `npm fund` for details
31 vulnerabilities (7 moderate, 24 high)
To address issues that do not require attention, run:
npm audit fix
To address all issues possible (including breaking changes), run:
npm audit fix --force
Some issues need review, and may require choosing
a different dependency.
Run `npm audit` for details.
npm warn install-scripts 2 packages had install scripts blocked because they are not covered by allowScripts:
npm warn install-scripts esbuild@0.28.1 (postinstall: node install.js)
npm warn install-scripts fsevents@2.3.3 (install: (install scripts present))
npm warn install-scripts
npm warn install-scripts Run `npm install-scripts ls` to review, or `npm install-scripts approve <pkg>` to allow.
The warnings don’t stop anything: the app builds and runs. The FAQ at the end of this page explains each of them.
If you install typescript@7 on its own instead, npm run build fails. The post Fixed: “TypeError: Cannot read properties of undefined (reading ‘Intrinsic’)” with TypeScript 7 shows that error and its cause.
Step 3: Update Biome’s Settings and Format the Starter Files
The newer Biome needs its settings file, biome.json, brought up to date. Run:
npx biome migrate --write
npm notice run npx
npm notice run 'biome' migrate --write
configuration ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
i Migration results:
- /Users/user/tanstack-lab/bookshop/biome.json: configuration successfully migrated.
The starter files don’t match Biome’s style yet, so format them and sort their imports. npm run check runs Biome’s check, and -- --write tells it to fix what it finds instead of only listing it:
npm run check -- --write
npm notice run check
npm notice run biome check --write
Checked 6 files in 10ms. Fixed 5 files.
From now on, npm run check on its own reports no problems. If you run it before this step, it reports 8 errors, and Fixed: “Some errors were emitted while running checks” in a New TanStack Start App explains them.
Step 4: Turn Off Netlify Edge Functions on Your Computer
The Netlify plugin in your project imitates Netlify’s features on your computer, so the app behaves as it will online. One of those features is Edge Functions, which Netlify runs in a runtime based on Deno, a JavaScript runtime like Node.js. The plugin downloads Deno 2.9.8, which rejects one of the options the plugin starts it with, and the dev server then stops right after the first page loads.
The Bookshop has no edge functions, so turn that feature off. Open vite.config.ts and change netlify() to:
vite.config.ts (excerpt)
netlify({ dev: { edgeFunctions: { enabled: false } } }),
The complete file:
vite.config.ts
import netlify from "@netlify/vite-plugin-tanstack-start";
import tailwindcss from "@tailwindcss/vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";
const config = defineConfig({
resolve: { tsconfigPaths: true },
plugins: [
devtools(),
netlify({ dev: { edgeFunctions: { enabled: false } } }),
tailwindcss(),
tanstackStart(),
viteReact(),
],
});
export default config;
This option comes from the Netlify plugin’s documentation. The post Fixed: “Could not establish a connection to the Netlify Edge Functions local development server” in TanStack Start shows the error and how its cause was found.
Step 5: Start the Dev Server
Start the app in development mode:
npm run dev
npm notice run dev
npm notice run vite dev --port 3000
10:41:47 AM [vite] ⬥ Netlify Environment loaded
10:41:47 AM [vite] ⬥ Netlify Middleware loaded. Emulating features: aiGateway, blobs, database, environmentVariables, functions, geolocation, headers, images, redirects, server, static.
10:41:47 AM [vite] ⬥ Netlify 💭 Linking this project to a Netlify site lets you deploy your site, use any environment variables defined on your team and site and much more. Run npx netlify init to get started.
VITE v8.3.8 ready in 1943 ms
➜ Local: http://localhost:3000/
➜ Network: use --host to expose
➜ press h + enter to show help
Vite is the tool that runs your app while you work on it. Open http://localhost:3000 in your browser to see the starter page:
Keep the terminal open: the app runs only while npm run dev runs. The terminal may also print a warning about a notFoundComponent. Your browser asked for a site icon, favicon.ico, which the app doesn’t have yet, so the warning is harmless.
Step 6: Take a Quick Tour of the Project
Open the bookshop folder in your code editor. These are the files you’ll use most:
| File | What it’s for |
|---|---|
src/routes/index.tsx | The home page, at the address /. |
src/routes/__root.tsx | The root route: the page around every page, with its <head> and styles. It always runs. |
src/router.tsx | Creates the router, which connects each address to its page. |
src/routeTree.gen.ts | The list of your routes. TanStack Start writes it for you when the dev server runs, so you never edit it. |
src/styles.css | Styles for every page. It loads Tailwind CSS. |
vite.config.ts | Settings for Vite and its plugins, such as TanStack Start and Netlify. |
package.json | The app’s packages and scripts, such as dev, build and check. |
biome.json | Settings for Biome, which formats and checks your code. |
netlify.toml | Settings Netlify uses when the site goes online. |
tsconfig.json | Settings for TypeScript. |
Each file in src/routes is a page, and its file name sets its address. This is called file-based routing, and Part 3 covers it in full.
Step 7: Change the Home Page
Open src/routes/index.tsx. createFileRoute("/") connects this file to the address /, and the Home function returns what the page shows.
A function that returns page content like this is a React component, and the HTML-like code inside it is JSX. className sets Tailwind CSS classes, such as text-4xl for large text.
Replace the whole file with this:
src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/")({ component: Home });
function Home() {
return (
<main className="mx-auto max-w-2xl p-8">
<h1 className="text-4xl font-bold">Welcome to the Bookshop</h1>
<p className="mt-4 text-lg">Find your next favourite book.</p>
<h2 className="mt-8 text-2xl font-semibold">Featured books</h2>
<ul className="mt-2 list-disc pl-6 text-lg">
<li>The Paper Lantern Café</li>
<li>Salt and Starlight</li>
</ul>
</main>
);
}
Save the file. The browser updates by itself, without a reload:
Clean Up
Stop the dev server: click in the terminal and press Ctrl+C. Keep the bookshop folder, because Part 3 continues from it.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Running the create command where a bookshop folder already exists | The CLI stops without creating the app | Run it in another folder, or choose another name |
Installing typescript@7 on its own | npm run build fails with a TypeError | Use the command in Step 2 |
Editing src/routeTree.gen.ts | TanStack Start replaces your changes | Change the files in src/routes instead |
| Closing the terminal | The page stops loading | Keep the terminal open while you work |
Troubleshooting
| Problem | Fix |
|---|---|
command not found: npx | Install Node.js 26, then open a new terminal window. |
| The dev server stops with “Could not establish a connection to the Netlify Edge Functions local development server” | Make the change in Step 4. |
npm run check reports errors | Run the two commands in Step 3. |
The terminal says Port 3000 is in use, trying another one... | Another app is using port 3000, so Vite picks the next free port. Open the address it prints after Local:, such as http://localhost:3001/. |
FAQ
Why does npm report 31 vulnerabilities? Most come from one advisory for picomatch, a package that build tools such as Vite use to match file names. The advisory lists no fixed version yet. It concerns file patterns that someone else supplies, which the Bookshop never takes. Don’t run npm audit fix --force: npm’s documentation says it can install breaking changes, and here it would move TanStack Start to an older release.
What does “install scripts blocked” mean? npm 12 doesn’t run a package’s install script until you approve it (npm docs). The two packages it names work without them: esbuild’s docs say it still works, only a little slower to start, and fsevents comes ready-built.
What do the “ERESOLVE overriding peer dependency” warnings mean? A package inside the Netlify plugin can optionally use TypeScript 7.1, which is still in preview, so npm notes that TypeScript 7.0 doesn’t match. Nothing breaks: the app builds, and the type check passes.
Can I use pnpm, Yarn or Bun instead of npm? Yes. The CLI’s --package-manager option also takes pnpm, yarn, bun and deno (CLI reference). This series uses npm, so its commands match yours.
Do I need a Netlify account now? No. Nothing goes online until a later part, which uses Netlify’s free plan.
Do I need to know React first? No. Each React idea gets a sentence or two where it first appears, with a link to the official React docs.
Conclusion
You created the Bookshop with the TanStack CLI, brought its tools up to date, ran it at http://localhost:3000 and changed its home page. Next, you add more pages and the links between them.
← Previous: Part 1: What Is TanStack Start? A Full-Stack React Framework Explained
Next → Part 3: Pages and Links: File-Based Routing: add pages with files, link them from a header and give wrong addresses a friendly 404 page.
Additional Resources
- Getting Started with TanStack Start
- TanStack CLI Reference
- File-Based Routing in the TanStack Router docs
- Announcing TypeScript 7.0, on the TypeScript blog
- Biome CLI reference
- Netlify’s TanStack Start plugin on GitHub
- Vite command line interface
- Your First Component on react.dev
- Download Node.js
TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.