start-core

TanStack Start 核心

TanStack Start 是一个基于 TanStack Router 和 Vite 构建的全栈 React 框架。它提供 SSR、流式传输、服务器函数（类型安全的 RPC）、中间件、服务器路由和通用部署。

CRITICAL：TanStack Start 中的所有代码默认都是同构的，会同时在服务器和客户端环境中运行。加载器会在服务器和客户端上运行。要让代码仅在服务器上运行，请使用 createServerFn。这是 AI Agent 最常犯的错误。 CRITICAL：TanStack Start 不是 Next.js。不要生成 getServerSideProps、"use server" 指令、app/layout.tsx 或任何 Next.js/Remix 模式。服务器专用代码请使用 createServerFn。 CRITICAL：类型会被完全推断。绝不要进行类型转换，也不要为推断出的值添加类型注解。

使用此入口技能选择一个主要工作流。不要加载所有 Start 子技能。仅当实现涉及相应边界时，才添加另一个技能；例如，受保护的变更需要 server-functions 和 auth-server-primitives，而公开的 REST 端点只需要 server-routes。

子技能

任务	子技能
类型安全的 RPC、数据获取、变更	start-core/server-functions/SKILL.md
请求/函数中间件、上下文、身份验证	start-core/middleware/SKILL.md
服务器端身份验证：会话、Cookie、OAuth、CSRF	start-core/auth-server-primitives/SKILL.md
同构执行、环境边界	start-core/execution-model/SKILL.md
与应用路由并存的 REST API 端点	start-core/server-routes/SKILL.md
托管、SSR 模式、预渲染、SEO	start-core/deployment/SKILL.md

快速决策树

Need to run code exclusively on the server (DB, secrets)?
  → start-core/server-functions

Need auth checks, logging, or shared logic across server functions?
  → start-core/middleware

Need to add login, sessions, OAuth, CSRF, password reset?
  → start-core/auth-server-primitives

Need to understand where code runs (server vs client)?
  → start-core/execution-model

Need a REST API endpoint (GET/POST/PUT/DELETE)?
  → start-core/server-routes

Need to deploy, configure SSR, or prerender?
  → start-core/deployment

全栈交付工作流

对于由 Start 路由加载的应用数据：

1. 将数据库、文件系统、机密信息和持久化代码放在 createServerFn 后面。
2. 在路由加载器中直接调用服务器函数。不要在 SSR 加载器中自行请求相对路径 /api/... URL。
3. 在服务器函数或中间件中验证所有输入并强制执行身份验证。beforeLoad 只能保护路由体验。
4. 变更完成后，使路由器或外部查询缓存失效；如果继续操作前 UI 必须显示最新数据，则等待刷新完成。
5. 对于架构变更，请更新存储、验证、处理器序列化、加载器和 UI。断言实际的运行时负载；仅进行类型检查无法发现被遗漏的序列化字段。

当原始 HTTP 契约本身就是产品时，请使用服务器路由：例如 Webhook、第三方客户端、信息源、文件响应或公开的 REST API。当 Start UI 和服务器路由共享数据时，让两者调用同一个服务器端服务，而不是让 SSR 加载器请求自己的 API 路由。

完成前，请测试初始 SSR 请求、客户端导航、变更后的刷新，以及对每个受保护端点直接发起的匿名请求。

项目设置

1. 安装依赖

npm i @tanstack/react-start @tanstack/react-router react react-dom
npm i -D vite @vitejs/plugin-react typescript

2. 配置 Vite

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

export default defineConfig({
  plugins: [
    // MUST come before react()
    tanstackStart(),
    viteReact(),
  ],
})

3. 创建路由器工厂

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
  })

  return router
}

4. 创建带文档外壳的根路由

// src/routes/__root.tsx
import type { ReactNode } from 'react'
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: 'My App' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

5. 创建带服务器函数的索引路由

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

const getGreeting = createServerFn({ method: 'GET' }).handler(async () => {
  return { message: 'Hello from the server!' }
})

export const Route = createFileRoute('/')({
  loader: () => getGreeting(),
  component: HomePage,
})

function HomePage() {
  const data = Route.useLoaderData()
  return <h1>{data.message}</h1>
}

常见错误

1. CRITICAL：在 Vite 配置中将 React 插件放在 Start 插件之前

// WRONG — route generation and server function compilation fail
plugins: [react(), tanstackStart()]

// CORRECT — Start plugin must come first
plugins: [tanstackStart(), react()]

2. HIGH：在 tsconfig 中启用 verbatimModuleSyntax

verbatimModuleSyntax 会导致服务器包泄漏到客户端包中。请保持禁用。

3. HIGH：根路由中缺少 Scripts 组件

必须在根路由的 <body> 中渲染 <Scripts /> 组件。否则，客户端 JavaScript 不会加载，水合会失败。

// WRONG — no Scripts
function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
      </body>
    </html>
  )
}

// CORRECT — Scripts in body
function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

版本说明

此技能适用于 @tanstack/start-client-core v1.170.14。