Tanstack Start

作者 tanstack-skills6f5521ecbdfb无许可证35 个星标收录于 2026年10月8日更新于 2026年10月8日仓库8个月前更新

Full-stack React framework powered by TanStack Router with SSR, streaming, server functions, and deployment to any hosting provider.

仅含说明Software Development

AI 生成的概览

TanStack Start 全栈 React 框架参考指南，涵盖服务器函数、中间件、API 路由、SSR 与部署。

功能: 该技能是 TanStack Start 的说明性参考资料，这是一个基于 TanStack Router、Vite 和 Nitro 的全栈 React 框架。内容涵盖项目搭建与配置、带校验的服务器函数、中间件组合、API 路由、流式 SSR 模式、部署预设以及常见陷阱。它产出的是指导说明和代码示例，而不是运行脚本或生成文件。
适用场景: 在搭建或开发 TanStack Start 应用，并需要路由、服务器函数、中间件、SSR 或部署目标方面的指导时使用。适合希望了解框架约定和代码模式的开发者，而非寻求可直接运行的工具。
运行要求: 不包含脚本，仅为说明性内容。按示例操作需要 Node.js 环境及 npm 或 npx，以及 @tanstack/react-start、@tanstack/react-router、react、react-dom、@tanstack/router-plugin、typescript、vite、vite-tsconfig-paths 等包，校验部分可选 zod。

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

bash

npx @tanstack/cli create my-app# Or manually:npm install @tanstack/react-start @tanstack/react-router react react-domnpm install -D @tanstack/router-plugin typescript vite vite-tsconfig-paths

npx @tanstack/cli create my-app# Or manually:npm install @tanstack/react-start @tanstack/react-router react react-domnpm 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

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

typescript

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',  },})

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

typescript

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

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

typescript

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

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

typescript

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

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

typescript

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

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

typescript

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 } })  })
// Usageconst adminAction = createServerFn({ method: 'POST' })  .middleware([adminMiddleware])  .handler(async ({ context }) => {    // context: { user: User; isAdmin: boolean }    return { success: true }  })

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 } })  })
// Usageconst adminAction = createServerFn({ method: 'POST' })  .middleware([adminMiddleware])  .handler(async ({ context }) => {    // context: { user: User; isAdmin: boolean }    return { success: true }  })

API Routes (Server Routes)

typescript

// app/routes/api/users.tsimport { 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 })  },})

// app/routes/api/users.tsimport { 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)

typescript

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

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)

typescript

// app.config.tsexport 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  },})

// app.config.tsexport 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

来源与署名

来源：tanstack-skills/tanstack-skills位于plugins/tanstack-start/skills/tanstack-start提交6f5521e

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Tanstack Start

TanStack Start Skills

Overview

Installation & Project Setup

Project Structure

Configuration (`app.config.ts`)

Server Functions (`createServerFn`)

Basic Server Functions

With Zod Validation

Middleware

Creating Middleware

Auth Middleware with Context

Chaining Middleware

API Routes (Server Routes)

SSR Strategies

Streaming SSR (Default)

Deployment

Supported Platforms (Nitro Presets)

Best Practices

Common Pitfalls

来源与署名

更多来自 tanstack-skills/tanstack-skills 的技能

Tanstack Virtual

Tanstack Table

Tanstack Store

Tanstack Router

Tanstack Ranger

Tanstack Query

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

Tanstack Start

TanStack Start Skills

Overview

Installation & Project Setup

Project Structure

Configuration (app.config.ts)

Server Functions (createServerFn)

Basic Server Functions

With Zod Validation

Middleware

Creating Middleware

Auth Middleware with Context

Chaining Middleware

API Routes (Server Routes)

SSR Strategies

Streaming SSR (Default)

Deployment

Supported Platforms (Nitro Presets)

Best Practices

Common Pitfalls

来源与署名

更多来自 tanstack-skills/tanstack-skills 的技能

Tanstack Virtual

Tanstack Table

Tanstack Store

Tanstack Router

Tanstack Ranger

Tanstack Query

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

Configuration (`app.config.ts`)

Server Functions (`createServerFn`)