Site icon JD Bots

TanStack Start Tutorial — Part 2: Create Your First TanStack Start App

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:

This is Part 2 of the TanStack Start Tutorial. The parts in Module A, Start Here:

All parts of the TanStack Start Tutorial

Module A: Start Here

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

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:

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:

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:

The starter page that the TanStack CLI creates.

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:

FileWhat it’s for
src/routes/index.tsxThe home page, at the address /.
src/routes/__root.tsxThe root route: the page around every page, with its <head> and styles. It always runs.
src/router.tsxCreates the router, which connects each address to its page.
src/routeTree.gen.tsThe list of your routes. TanStack Start writes it for you when the dev server runs, so you never edit it.
src/styles.cssStyles for every page. It loads Tailwind CSS.
vite.config.tsSettings for Vite and its plugins, such as TanStack Start and Netlify.
package.jsonThe app’s packages and scripts, such as dev, build and check.
biome.jsonSettings for Biome, which formats and checks your code.
netlify.tomlSettings Netlify uses when the site goes online.
tsconfig.jsonSettings 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:

The Bookshop home page after the edit.

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

MistakeWhat happensDo this instead
Running the create command where a bookshop folder already existsThe CLI stops without creating the appRun it in another folder, or choose another name
Installing typescript@7 on its ownnpm run build fails with a TypeErrorUse the command in Step 2
Editing src/routeTree.gen.tsTanStack Start replaces your changesChange the files in src/routes instead
Closing the terminalThe page stops loadingKeep the terminal open while you work

Troubleshooting

ProblemFix
command not found: npxInstall 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 errorsRun 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

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