TanStack Start Skills

Overview

TanStack Start is a full-stack React framework built on TanStack Router, powered by Vite and Nitro (via Vinxi). It provides server-side rendering, streaming, server functions (RPC), middleware, API routes, and deploys to any platform via Nitro presets.

Package: @tanstack/react-start

Router Plugin: @tanstack/router-plugin

Build Tool: Vinxi (Vite + Nitro)

Status: RC (Release Candidate)

RSC Support: React Server Components support is in active development and will land as a non-breaking v1.x addition

Installation & Project Setup

npx @tanstack/cli create my-app

# Or manually:

npm install @tanstack/react-start @tanstack/react-router react react-dom

npm install -D @tanstack/router-plugin typescript vite vite-tsconfig-paths

Project Structure

my-app/

  app/

    routes/

      __root.tsx          # Root layout

      index.tsx           # / route

      posts.$postId.tsx   # /posts/:postId

      api/

        users.ts          # /api/users API route

    client.tsx            # Client entry

    router.tsx            # Router creation

    ssr.tsx               # SSR entry

    routeTree.gen.ts      # Auto-generated route tree

  app.config.ts           # TanStack Start config

  tsconfig.json

  package.json

Configuration ( app.config.ts )

import { defineConfig } from '@tanstack/react-start/config'

import viteTsConfigPaths from 'vite-tsconfig-paths'

export default defineConfig({

  vite: {

    plugins: [

      viteTsConfigPaths({ projects: ['./tsconfig.json'] }),

    ],

  },

  server: {

    preset: 'node-server', // 'vercel' | 'netlify' | 'cloudflare-pages' | etc.

  },

  tsr: {

    appDirectory: './app',

    routesDirectory: './app/routes',

    generatedRouteTree: './app/routeTree.gen.ts',

  },

})

Server Functions ( createServerFn )

Server functions provide type-safe RPC calls between client and server.

Basic Server Functions

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

// GET (data fetching, cacheable)

const getUsers = createServerFn()

  .handler(async () => {

    const users = await db.query.users.findMany()

    return users

  })

// POST (mutations, side effects)

const createUser = createServerFn({ method: 'POST' })

  .validator((data: { name: string; email: string }) => data)

  .handler(async ({ data }) => {

    const user = await db.insert(users).values(data).returning()

    return user

  })

With Zod Validation

import { z } from 'zod'

const updateUser = createServerFn({ method: 'POST' })

  .validator(

    z.object({

      id: z.string(),

      name: z.string().min(1),

      email: z.string().email(),

    })

  )

  .handler(async ({ data }) => {

    // data is fully typed: { id: string; name: string; email: string }

    return await db.update(users).set(data).where(eq(users.id, data.id))

  })

Middleware

Creating Middleware

import { createMiddleware } from '@tanstack/react-start'

const loggingMiddleware = createMiddleware().handler(async ({ next }) => {

  console.log('Request started')

  const result = await next()

  console.log('Request completed')

  return result

})

Auth Middleware with Context

const authMiddleware = createMiddleware().handler(async ({ next }) => {

  const request = getWebRequest()

  const session = await getSession(request)

  if (!session?.user) {

    throw redirect({ to: '/login' })

  }

  // Pass typed context to handler

  return next({ context: { user: session.user } })

})

Chaining Middleware

const adminMiddleware = createMiddleware()

  .middleware([authMiddleware])

  .handler(async ({ next, context }) => {

    // context.user is typed from authMiddleware

    if (context.user.role !== 'admin') {

      throw redirect({ to: '/unauthorized' })

    }

    return next({ context: { isAdmin: true } })

  })

// Usage

const adminAction = createServerFn({ method: 'POST' })

  .middleware([adminMiddleware])

  .handler(async ({ context }) => {

    // context: { user: User; isAdmin: boolean }

    return { success: true }

  })

API Routes (Server Routes)

// app/routes/api/users.ts

import { createAPIFileRoute } from '@tanstack/react-start/api'

export const APIRoute = createAPIFileRoute('/api/users')({

  GET: async ({ request }) => {

    const users = await db.query.users.findMany()

    return Response.json(users)

  },

  POST: async ({ request }) => {

    const body = await request.json()

    const user = await db.insert(users).values(body).returning()

    return new Response(JSON.stringify(user), { status: 201 })

  },

})

SSR Strategies

Streaming SSR (Default)

export const Route = createFileRoute('/dashboard')({

  loader: async () => ({

    criticalData: await fetchCriticalData(),

    deferredData: defer(fetchSlowData()),

  }),

  component: Dashboard,

})

function Dashboard() {

  const { criticalData, deferredData } = Route.useLoaderData()

  return (

    <div>

      <CriticalSection data={criticalData} />

      <Suspense fallback={<Loading />}>

        <Await promise={deferredData}>

          {(data) => <SlowSection data={data} />}

        </Await>

      </Suspense>

    </div>

  )

}

Deployment

Supported Platforms (Nitro Presets)

// app.config.ts

export default defineConfig({

  server: {

    preset: 'node-server',        // Self-hosted Node.js

    // preset: 'vercel',          // Vercel

    // preset: 'netlify',         // Netlify

    // preset: 'cloudflare-pages', // Cloudflare Pages

    // preset: 'aws-lambda',      // AWS Lambda

    // preset: 'deno-server',     // Deno Deploy

    // preset: 'bun',             // Bun

  },

})

Best Practices

• Use validators for all server function inputs - runtime safety and TypeScript inference

• Compose middleware for cross-cutting concerns (auth, logging, rate limiting)

• **Use createServerFn GET** for data fetching (cacheable, preloadable)

• **Use createServerFn POST** for mutations and side effects

• **Use beforeLoad** for route-level auth guards

• **Use defer()** for non-critical data to improve TTFB

• **Set defaultPreload: 'intent'** on the router for instant navigation

• Co-locate server functions with the routes that use them

Common Pitfalls

• Server functions cannot close over client-side variables (they're extracted to separate bundles)

• Data returned from server functions must be serializable

• Forgetting await in loaders leads to streaming issues

• Importing server-only code in client bundles causes build errors

• Missing declare module '@tanstack/react-router' loses all type safety