TanStack Start

https://tanstack.com/start/latest/docs
Admin
TanStack Start is an alpha web development framework that integrates various TanStack libraries such...
Tokens:153,256
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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### Create a TanStack Start app using TanStack CLI

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

Initialize a new TanStack Start project locally before pushing it to a GitHub repository for deployment.

```bash
npx @tanstack/cli@latest create
```

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

### 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 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"
```

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

### 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
```

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

### 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')
  })
```

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

### 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 }
})
```

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

### 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
```

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

### 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
```

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

### 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()],
})
```

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

### 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)
      },
    },
  },
})
```

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

### 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
```

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

### 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!
```

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

### 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
```

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

### 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
  },
)
```

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

### File organization example for server functions

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

Shows a recommended directory structure for separating server function wrappers, server-only helpers, and shared schemas.

```text
src/utils/
├── users.functions.ts   # Server function wrappers (createServerFn)
├── users.server.ts      # Server-only helpers (DB queries, internal logic)
└── schemas.ts           # Shared validation schemas (client-safe)
```

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

### Analyze client bundle

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

Use these commands to build the project and inspect the client distribution for accidental inclusion of server-only code.

```bash
# Analyze client bundle
npm run build
# Check dist/client for any server-only imports
```

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

### Install Tailwind CSS v4 with Vite

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

Install Tailwind CSS and the Vite integration package.

```shell
npm install tailwindcss @tailwindcss/vite
```

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

### Install Tailwind CSS v4 with Rsbuild

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

Install Tailwind CSS, PostCSS, and the PostCSS plugin for Rsbuild.

```shell
npm install tailwindcss @tailwindcss/postcss postcss
```

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

### Configure Rsbuild for TanStack Start

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

The rsbuild.config.ts file configures the server port and integrates the TanStack Start plugin.

```ts
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [pluginReact(), tanstackStart()],
})
```

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

### Configure vite.config.ts

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

Configure the TanStack Start plugin in vite.config.ts, ensuring the React plugin is placed after the start plugin.

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

export default defineConfig({
  server: {
    port: 3000,
  },
  resolve: {
    tsconfigPaths: true,
  },
  plugins: [
    tanstackStart(),
    // react's vite plugin must come after start's vite plugin
    viteReact(),
  ],
})
```

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

### Configure Environment Variable Prefixes

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

Demonstrates the required prefixing for client-side environment variables and how they affect build-time bundling.

```bash
# ❌ Won't work in client code
API_KEY=abc123

# ✅ Works in client code
VITE_API_KEY=abc123

# ❌ Won't bundle the variable (assuming it is not set in the environment of the build)
npm run build

# ✅ Works in client code and will bundle the variable for production
VITE_API_KEY=abc123 npm run build
```

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

### 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>
  )
}
```

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

### Install Tailwind CSS v3 and peer dependencies

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

Install Tailwind CSS v3, PostCSS, and Autoprefixer as dev dependencies.

```shell
npm install -D tailwindcss@3 postcss autoprefixer
```

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

### Build the application

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

Execute the build npm script to generate production assets.

```sh
npm run build
```

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

### Install RSC dependencies for Rsbuild

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

Install the required Rsbuild React dependencies. Rsbuild does not need a separate RSC plugin.

```bash
npm install -D @rsbuild/core @rsbuild/plugin-react
```

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

### Global Fetch via createStart

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

Shows how to set a default custom fetch for all server functions by providing serverFns.fetch in createStart. This global fetch has lower priority than middleware and call-site fetch, and only applies on the client side.

```tsx
// src/start.ts
import { createStart } from '@tanstack/react-start'
import type { CustomFetch } from '@tanstack/react-start'

const globalFetch: CustomFetch = async (url, init) => {
  console.log('Global fetch:', url)
  // Add retry logic, telemetry, etc.
  return fetch(url, init)
}

export const startInstance = createStart(() => {
  return {
    serverFns: {
      fetch: globalFetch,
    },
  }
})
```
Tokens:
Raw