TanStack Start

https://tanstack.com/start/latest/docs/framework/react/
Admin
TanStack Start is a full-stack React framework for building modern web applications with integrated...
Tokens:154,463
Snippets:1,309
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies and start the development server

Source: https://tanstack.com/start/latest/docs/framework/react/tutorial/fetching-external-api.md

After project setup, install dependencies with pnpm and start the development server. The app will be accessible at localhost:3000.

```bash
pnpm i
pnpm dev
```

--------------------------------

### Clone the Basic example project

Source: https://tanstack.com/start/latest/docs/framework/react/getting-started.md

Clone the official Basic example repository to start with a working codebase.

```bash
npx gitpick TanStack/router/tree/main/examples/react/start-basic start-basic
cd start-basic
npm install
npm run dev
```

--------------------------------

### Create and navigate to a new TanStack Start project

Source: https://tanstack.com/start/latest/docs/framework/react/tutorial/fetching-external-api.md

Run these commands to scaffold a new TanStack Start project named 'movie-discovery' and enter its directory. The setup script will prompt for configuration choices; pressing enter accepts defaults. Optionally, a --add-on flag can be passed to include options like Shadcn, Clerk, Convex, or TanStack Query.

```bash
pnpx create-start-app movie-discovery
cd movie-discovery
```

--------------------------------

### Clone and install the reference application

Source: https://tanstack.com/start/latest/docs/framework/react/migrate-from-next-js.md

Commands to clone the TanStack Router repository, install dependencies, build the package, and navigate to the migration example.

```sh
git clone --depth 1 https://github.com/TanStack/router.git
cd router
pnpm install
pnpm nx run @tanstack/react-start:build
cd examples/react/start-next-migration
```

--------------------------------

### Example .env Configuration

Source: https://tanstack.com/start/latest/docs/framework/react/guide/environment-variables.md

Provides examples for .env, .env.local, and .env.production files.

```bash
# Public configuration (Vite uses VITE_; Rsbuild uses PUBLIC_ by default)
VITE_APP_NAME=My TanStack Start App
VITE_API_URL=https://api.example.com
VITE_SENTRY_DSN=https://...
PUBLIC_APP_NAME=My TanStack Start App
PUBLIC_API_URL=https://api.example.com
PUBLIC_SENTRY_DSN=https://...

# Server configuration templates
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
```

```bash
# Override for local development
DATABASE_URL=postgresql://user:password@localhost:5432/myapp_local
STRIPE_SECRET_KEY=sk_test_...
JWT_SECRET=your-local-secret
```

```bash
# Production overrides
VITE_API_URL=https://api.myapp.com
PUBLIC_API_URL=https://api.myapp.com
DATABASE_POOL_SIZE=20
```

--------------------------------

### Install TanStack Start and Router

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Installs the core TanStack Start and Router packages via npm.

```shell
npm i @tanstack/react-start @tanstack/react-router
```

--------------------------------

### Project structure after setup

Source: https://tanstack.com/start/latest/docs/framework/react/tutorial/fetching-external-api.md

Shows the expected file and folder layout of the generated TanStack Start project, including routes, types, router configuration, and configuration files.

```text
/movie-discovery
├── src/
│   ├── routes/
│   │   ├── __root.tsx                    # Root layout
│   │   ├── index.tsx                     # Home page
│   │   └── fetch-movies.tsx              # Movie fetching route
│   ├── types/
│   │   └── movie.ts                      # Movie type definitions
│   ├── router.tsx                        # Router configuration
│   ├── routeTree.gen.ts                  # Generated route tree
│   └── styles.css                        # Global styles
├── public/                               # Static assets
├── vite.config.ts or rsbuild.config.ts    # TanStack Start configuration
├── package.json                          # Project dependencies
└── tsconfig.json                         # TypeScript configuration
```

--------------------------------

### Run end-to-end tests for React Query example

Source: https://tanstack.com/start/latest/docs/framework/react/guide/tanstack-query.md

Commands to navigate to the example directory, install Playwright browsers, and execute the test suite in both development and production modes.

```sh
cd examples/react/start-basic-react-query
pnpm exec playwright install chromium
pnpm test:e2e
pnpm build
QUERY_EXAMPLE_PRODUCTION=1 pnpm test:e2e
```

--------------------------------

### Install React Dependencies

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Installs React and ReactDOM, required for TanStack Start applications.

```shell
npm i react react-dom
```

--------------------------------

### Start the production application

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Run the start npm script to launch the production server.

```sh
npm run start
```

--------------------------------

### Quick Start: Setting Execution Boundaries

Source: https://tanstack.com/start/latest/docs/framework/react/guide/code-execution-patterns.md

Imports the execution boundary functions and shows examples of server functions, server-only utilities, client-only utilities, and isomorphic functions with different implementations per environment.

```tsx
import {
  createServerFn,
  createServerOnlyFn,
  createClientOnlyFn,
  createIsomorphicFn,
} from '@tanstack/react-start'

// Server function (RPC call)
const getUsers = createServerFn().handler(async () => {
  return await db.users.findMany()
})

// Server-only utility (crashes on client)
const getSecret = createServerOnlyFn(() => process.env.API_SECRET)

// Client-only utility (crashes on server)
const saveToStorage = createClientOnlyFn((data: any) => {
  localStorage.setItem('data', JSON.stringify(data))
})

// Different implementations per environment
const logger = createIsomorphicFn()
  .server((msg) => console.log(`[SERVER]: ${msg}`))
  .client((msg) => console.log(`[CLIENT]: ${msg}`))
```

--------------------------------

### Build and start the Bun production server

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Build the TanStack Start application and launch the Bun server using the reference server script.

```sh
bun run build
```

```sh
bun run server.ts
```

--------------------------------

### Install content-collections packages

Source: https://tanstack.com/start/latest/docs/framework/react/guide/rendering-markdown.md

Install the required packages for content-collections.

```bash
npm install @content-collections/core @content-collections/vite
```

--------------------------------

### Create a TanStack Start project

Source: https://tanstack.com/start/latest/docs/framework/react/tutorial/reading-writing-file.md

Initialize a new project using the TanStack CLI and navigate into the directory.

```bash
pnpx @tanstack/cli@latest create devjokes
cd devjokes
```

--------------------------------

### Example Bun server startup logs

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Displays sample console output showing memory preloading statistics and server startup confirmation.

```txt
📦 Loading static assets from ./dist/client...
   Max preload size: 5.00 MB

📁 Preloaded into memory:
   /assets/index-a1b2c3d4.js           45.23 kB │ gzip:  15.83 kB
   /assets/index-e5f6g7h8.css           12.45 kB │ gzip:   4.36 kB

💾 Served on-demand:
   /assets/vendor-i9j0k1l2.js          245.67 kB │ gzip:  86.98 kB

✅ Preloaded 2 files (57.68 KB) into memory
🚀 Server running at http://localhost:3000
```

--------------------------------

### Clone a specific example project

Source: https://tanstack.com/start/latest/docs/framework/react/getting-started.md

Replace EXAMPLE_SLUG with the desired example slug to clone and run a specific project template.

```bash
npx gitpick TanStack/router/tree/main/examples/react/EXAMPLE_SLUG my-new-project
cd my-new-project
npm install
npm run dev
```

--------------------------------

### Install Rsbuild dependencies

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Install Rsbuild and the React plugin.

```shell
npm i -D @rsbuild/core @rsbuild/plugin-react
```

--------------------------------

### Install Vite dependencies

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Install Vite and the React plugin.

```shell
npm i -D vite @vitejs/plugin-react
```

--------------------------------

### Sentry Quick Setup (Client and Server)

Source: https://tanstack.com/start/latest/docs/framework/react/guide/observability.md

Initialize Sentry on the client with @sentry/react and capture exceptions in server functions using @sentry/node. The client setup uses VITE_SENTRY_DSN and NODE_ENV from the environment. The server function wraps a risky operation and rethrows the error after capturing it.

```tsx
// Client-side (app.tsx)
import * as Sentry from '@sentry/react'

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.NODE_ENV,
})

// Server functions
import * as Sentry from '@sentry/node'

const serverFn = createServerFn().handler(async () => {
  try {
    return await riskyOperation()
  } catch (error) {
    Sentry.captureException(error)
    throw error
  }
})
```

--------------------------------

### Install and configure Nitro in vite.config.ts

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Install nitro and add the nitro/vite plugin to your Vite configuration to enable multi-provider deployment with TanStack Start.

```bash
npm install nitro
```

```tsx
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [tanstackStart(), nitro(), viteReact()],
})
```

--------------------------------

### Run Bun server with basic configuration

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Start the Bun production server using default settings or pass optional environment variables such as PORT and ASSET_PRELOAD_VERBOSE_LOGGING.

```sh
# Basic usage - just works out of the box
bun run server.ts

# Common configurations
PORT=8080 bun run server.ts  # Custom port
ASSET_PRELOAD_VERBOSE_LOGGING=true bun run server.ts  # See what's happening
```

--------------------------------

### Install TypeScript dependencies

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Install TypeScript and necessary type definitions.

```shell
npm i -D typescript @types/react @types/react-dom @types/node
```

--------------------------------

### Configure Vite build and start npm scripts

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Add these scripts to your package.json to build with Vite and start the server using Node.js from the Nitro build output.

```json
    "build": "vite build",
    "start": "node .output/server/index.mjs"
```

--------------------------------

### Configure and deploy with @netlify/vite-plugin-tanstack-start and Netlify CLI

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Install `@netlify/vite-plugin-tanstack-start` and add it to `vite.config.ts` to configure builds and local emulation. Deploy using `npx netlify deploy`, which prompts initialization and auto-configures build settings for new projects.

```bash
npm install --save-dev @netlify/vite-plugin-tanstack-start
# or...
pnpm add --save-dev @netlify/vite-plugin-tanstack-start
# or yarn, bun, etc.
```

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import netlify from '@netlify/vite-plugin-tanstack-start' // ← add this
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart(),
    netlify(), // ← add this (anywhere in the array is fine)
    viteReact(),
  ],
})
```

```bash
npx netlify deploy
```

--------------------------------

### Directory structure before and after migration

Source: https://tanstack.com/start/latest/docs/framework/react/migrate-from-next-js.md

Shows the file layout of a Next.js app and the corresponding TanStack Start structure. The Start Vite plugin generates src/routeTree.gen.ts, and src/router.tsx returns a new router using that tree.

```text
next-app/                 # Before: Next.js App Router
  app/
    layout.tsx
    page.tsx
    posts/[slug]/page.tsx
    actions.ts
src/                      # After: TanStack Start
  router.tsx
  routes/
    __root.tsx
    index.tsx
    posts.$slug.tsx
  server/account.ts
vite.config.ts
```

--------------------------------

### Create server functions with createServerFn (GET and POST)

Source: https://tanstack.com/start/latest/docs/framework/react/guide/server-functions.md

Shows how to define server functions using createServerFn. The first uses the default GET method, the second specifies POST. Both return data from the server.

```tsx
import { createServerFn } from '@tanstack/react-start'

// GET request (default)
export const getData = createServerFn().handler(async () => {
  return { message: 'Hello from server!' }
})

// POST request
export const saveData = createServerFn({ method: 'POST' }).handler(async () => {
  // Server-only logic
  return { success: true }
})
```

--------------------------------

### Authentication Provider Setup

Source: https://tanstack.com/start/latest/docs/framework/react/guide/environment-variables.md

Separates server-side configuration from client-side provider setup to ensure secrets remain on the server.

```typescript
// src/lib/auth.ts (Server)
export const authConfig = {
  secret: process.env.AUTH_SECRET,
  providers: {
    auth0: {
      domain: process.env.AUTH0_DOMAIN,
      clientId: process.env.AUTH0_CLIENT_ID,
      clientSecret: process.env.AUTH0_CLIENT_SECRET, // Server-only
    }
  }
}

// src/components/AuthProvider.tsx (Client)
export function AuthProvider({ children }: { children: React.ReactNode }) {
  return (
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN}
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      // No client secret here - it stays on the server
    >
      {children}
    </Auth0Provider>
  )
}
```

--------------------------------

### Middleware Execution Order Example

Source: https://tanstack.com/start/latest/docs/framework/react/guide/middleware.md

This example demonstrates the dependency-first execution order of middleware. The log order is: `globalMiddleware1`, `globalMiddleware2`, `a`, `b`, `c`, `d`, `fn`.

```tsx
import { createMiddleware, createServerFn } from '@tanstack/react-start'

const globalMiddleware1 = createMiddleware({ type: 'function' }).server(
  async ({ next }) => {
    console.log('globalMiddleware1')
    return next()
  },
)

const globalMiddleware2 = createMiddleware({ type: 'function' }).server(
  async ({ next }) => {
    console.log('globalMiddleware2')
    return next()
  },
)

const a = createMiddleware({ type: 'function' }).server(async ({ next }) => {
  console.log('a')
  return next()
})

const b = createMiddleware({ type: 'function' })
  .middleware([a])
  .server(async ({ next }) => {
    console.log('b')
    return next()
  })

const c = createMiddleware({ type: 'function' })
  .middleware()
  .server(async ({ next }) => {
    console.log('c')
    return next()
  })

const d = createMiddleware({ type: 'function' })
  .middleware([b, c])
  .server(async () => {
    console.log('d')
  })

const fn = createServerFn()
  .middleware([d])
  .server(async () => {
    console.log('fn')
  })
```

--------------------------------

### Environment File Hierarchy

Source: https://tanstack.com/start/latest/docs/framework/react/guide/environment-variables.md

Displays the order in which TanStack Start loads environment files.

```bash
.env.local          # Local overrides (add to .gitignore)
.env.production     # Production-specific variables
.env.development    # Development-specific variables
.env                # Default variables (commit to git)
```

--------------------------------

### Install vite-tsconfig-paths for Vite 7 and earlier

Source: https://tanstack.com/start/latest/docs/framework/react/guide/path-aliases.md

Command to install the `vite-tsconfig-paths` plugin, which is required to enable path aliases in Vite 7 and earlier.

```sh
npm install -D vite-tsconfig-paths
```

--------------------------------

### Monitor Server Functions and Routes

Source: https://tanstack.com/start/latest/docs/framework/react/guide/observability.md

Create a middleware to track transactions and register it in your start instance configuration.

```ts
// newrelic-middleware.ts
import newrelic from 'newrelic'
import { createMiddleware } from '@tanstack/react-start'

export const nrTransactionMiddleware = createMiddleware().server(
  async ({ request, next }) => {
    const reqPath = new URL(request.url).pathname
    newrelic.setControllerName(reqPath, request.method ?? 'GET')
    return await next()
  },
)
```

```ts
// start.ts
import { createStart } from '@tanstack/react-start'
import { nrTransactionMiddleware } from './newrelic-middleware'

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [nrTransactionMiddleware],
  }
})
```

--------------------------------

### Project directory structure

Source: https://tanstack.com/start/latest/docs/framework/react/tutorial/reading-writing-file.md

The standard file and folder structure for a TanStack Start project.

```text
/devjokes
├── src/
│   ├── routes/
│   │   ├── demo/                         # Demo routes
│   │   ├── __root.tsx                    # Root layout
│   │   └── index.tsx                     # Home page
│   ├── components/                       # React components
│   ├── data/                             # Data files
│   ├── router.tsx                        # Router configuration
│   ├── routeTree.gen.ts                  # Generated route tree
│   └── styles.css                        # Global styles
├── public/                               # Static assets
├── vite.config.ts or rsbuild.config.ts   # TanStack Start configuration
├── package.json                          # Project dependencies
└── tsconfig.json                         # TypeScript configuration
```

--------------------------------

### Configure transformAssets with cache and warmup

Source: https://tanstack.com/start/latest/docs/framework/react/guide/cdn-asset-urls.md

Example configuration for transformAssets enabling both caching and server-side warmup.

```ts
transformAssets: {
  transform: process.env.CDN_ORIGIN || '',
  cache: true,
  warmup: true,
}
```

--------------------------------

### TypeScript Configuration for TanStack Start

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Recommended tsconfig.json settings for TanStack Start. Keep verbatimModuleSyntax disabled to avoid server bundles leaking into client bundles.

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}
```

--------------------------------

### Install Cloudflare Vite Plugin and Wrangler

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Installs the required Cloudflare Vite plugin and Wrangler CLI as development dependencies for deploying to Cloudflare Workers.

```bash
pnpm add -D @cloudflare/vite-plugin wrangler
```

--------------------------------

### Environment Variable Prefixes

Source: https://tanstack.com/start/latest/docs/framework/react/guide/environment-variables.md

Examples of server-only variables without prefixes and client-safe variables using VITE_ or PUBLIC_ prefixes.

```bash
# ✅ Server-only (no prefix)
DATABASE_URL=postgresql://...
JWT_SECRET=super-secret-key
STRIPE_SECRET_KEY=sk_live_...

# ✅ Client-safe (Vite uses VITE_; Rsbuild uses PUBLIC_ by default)
VITE_APP_NAME=My App
VITE_API_URL=https://api.example.com
VITE_SENTRY_DSN=https://...
PUBLIC_APP_NAME=My App
PUBLIC_API_URL=https://api.example.com
PUBLIC_SENTRY_DSN=https://...
```

--------------------------------

### Configure Rsbuild Node.js runtime using srvx

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Install srvx and define package.json scripts to serve static client assets and forward dynamic requests to the Rsbuild server bundle.

```sh
npm install srvx
```

```json
    "build": "rsbuild build",
    "start": "srvx --prod -s ../client dist/server/index.js"
```

--------------------------------

### Install React 19 for Bun deployment

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Bun-specific deployment requires react and react-dom packages to be at version 19.0.0 or higher.

```sh
bun install react@19 react-dom@19
```

--------------------------------

### Deploy Application to Cloudflare Workers

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Executes the deploy script to build and deploy the TanStack Start application to Cloudflare Workers via Wrangler.

```bash
pnpm run deploy
```

--------------------------------

### Configure Cloudflare Workers in wrangler.jsonc

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Specifies the Wrangler configuration file including compatibility settings and the server entry point for TanStack Start.

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "tanstack-start-app",
  "compatibility_date": "2025-09-02",
  "compatibility_flags": ["nodejs_compat"],
  "main": "@tanstack/react-start/server-entry"
}
```

--------------------------------

### Enable FastResponse optimization for Node.js deployments

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Install srvx and replace globalThis.Response in src/server.ts to optimize response throughput on Node.js Nitro deployments.

```bash
npm install srvx
```

```ts
import { FastResponse } from 'srvx'
globalThis.Response = FastResponse
```

--------------------------------

### Define Rsbuild ServerEntry type

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Type definition for the fetch-style Start server entry exported by an Rsbuild production build.

```ts
type ServerEntry = {
  fetch(request: Request): Response | Promise<Response>
}
```

--------------------------------

### Configure Cloudflare Plugin in vite.config.ts

Source: https://tanstack.com/start/latest/docs/framework/react/guide/hosting.md

Configures the Cloudflare plugin with SSR environment options alongside the TanStack Start and React plugins in Vite.

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    cloudflare({ viteEnvironment: { name: 'ssr' } }),
    tanstackStart(),
    viteReact(),
  ],
})
```

--------------------------------

### Define a Server Route with GET handler

Source: https://tanstack.com/start/latest/docs/framework/react/guide/server-routes.md

Example of defining a server route in routes/hello.ts using the server property to handle GET requests.

```ts
// routes/hello.ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/hello')({
  server: {
    handlers: {
      GET: async ({ request }) => {
        return new Response('Hello, World! from ' + request.url)
      },
    },
  },
})
```

--------------------------------

### Use Tailwind CSS in a component

Source: https://tanstack.com/start/latest/docs/framework/react/guide/tailwind-integration.md

Example of using Tailwind CSS classes in a TanStack Start route component.

```tsx
// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

function Home() {
  return <div className="bg-red-500 text-white p-4">Hello World</div>
}
```

--------------------------------

### Initialize Project Directory with npm

Source: https://tanstack.com/start/latest/docs/framework/react/build-from-scratch.md

Creates a new project directory and initializes it with npm. Use your package manager of choice instead of npm if preferred.

```shell
mkdir myApp
cd myApp
npm init -y
```

--------------------------------

### Setting headers in a server route handler

Source: https://tanstack.com/start/latest/docs/framework/react/guide/server-routes.md

This example demonstrates how to define a GET handler in a route file and set a custom 'Content-Type' header in the returned Response object.

```ts
// routes/hello.ts
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/hello')({
  server: {
    handlers: {
      GET: async ({ request }) => {
        return new Response('Hello, World!', {
          headers: {
            'Content-Type': 'text/plain',
          },
        })
      },
    },
  },
})
// Visit /hello to see the response
// Hello, World!
```

--------------------------------

### Connect and interact with a database using server functions

Source: https://tanstack.com/start/latest/docs/framework/react/guide/databases.md

An abstract example demonstrating how to initialize a database client and use createServerFn to perform read and write operations.

```tsx
import { createServerFn } from '@tanstack/react-start'

const db = createMyDatabaseClient()

export const getUser = createServerFn().handler(async ({ context }) => {
  const user = await db.getUser(context.userId)
  return user
})

export const createUser = createServerFn({ method: 'POST' }).handler(
  async ({ data }) => {
    const user = await db.createUser(data)
    return user
  },
)
```
Tokens:
Raw