react-start

React Start (@tanstack/react-start)

这是 React Start 入门技能。请按以下工作流操作，然后只加载负责你要修改的边界的包技能。开始前不要完整阅读 start-core、Router Core 和 React Router 手册。

React Server Components 模式请参阅 react-start/server-components。

CRITICAL：默认情况下，所有代码都是同构的。加载器会在服务端和客户端运行。服务端专属逻辑请使用 createServerFn。

CRITICAL：不要将 @tanstack/react-start 与 Next.js 或 Remix 混淆。它们是完全不同的框架，API 也各不相同。

CRITICAL：类型会被完全推断。切勿强制转换类型，也不要为已推断的值添加类型注解。

全栈工作流

1. 使用 createFileRoute 定义路由和组件。
2. 将私有或服务端专属的读写操作放入 createServerFn；在加载器中直接调用读取操作。
3. 在组件中使用 useServerFn 执行变更，然后在写入操作完成后使路由或查询缓存失效。
4. 在每个私有服务端函数或服务端路由中强制执行身份验证。另行添加 beforeLoad，以改善导航体验。
5. 运行初始 SSR 流程、客户端导航、变更并重新加载、匿名用户直接请求端点、运行时响应断言、类型测试和生产构建。

仅在需要原始 HTTP 端点时，才加载 start-core/server-routes，而非 server-functions。仅针对具体路由问题（例如参数或搜索验证）加载 router-core/*。

包 API

@tanstack/react-start 重新导出 @tanstack/start-client-core 中的所有内容，并额外提供：

• useServerFn — 用于在组件中调用服务端函数的 React Hook

所有核心 API（createServerFn、createMiddleware、createStart、createIsomorphicFn、createServerOnlyFn、createClientOnlyFn）都可从 @tanstack/react-start 导入。

服务端实用工具（getRequest、getRequestHeader、setResponseHeader、setResponseHeaders、setResponseStatus）从 @tanstack/react-start/server 导入。

完整项目设置

1. 安装依赖

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

2. package.json

{
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "node .output/server/index.mjs"
  }
}

3. tsconfig.json

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

4. 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: [
    tanstackStart(), // MUST come before react()
    viteReact(),
  ],
})

5. 路由工厂（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
}

6. 根路由（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 TanStack Start App' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  )
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

7. 索引路由（src/routes/index.tsx）

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

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

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

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

useServerFn Hook

使用 useServerFn，即可在 React 组件中通过适当的集成调用服务端函数：

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

const updatePost = createServerFn({ method: 'POST' })
  .validator((data: { id: string; title: string }) => data)
  .handler(async ({ data }) => {
    await db.posts.update(data.id, { title: data.title })
    return { success: true }
  })

function EditPostForm({ postId }: { postId: string }) {
  const updatePostFn = useServerFn(updatePost)
  const [title, setTitle] = useState('')

  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault()
        await updatePostFn({ data: { id: postId, title } })
      }}
    >
      <input value={title} onChange={(e) => setTitle(e.target.value)} />
      <button type="submit">Save</button>
    </form>
  )
}

全局 Start 配置（src/start.ts）

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

const requestLogger = createMiddleware().server(async ({ next, request }) => {
  console.log(`${request.method} ${request.url}`)
  return next()
})

export const startInstance = createStart(() => ({
  requestMiddleware: [requestLogger],
}))

React 专用组件

@tanstack/react-router 中的所有路由组件都可在 Start 中使用：

• <RouterProvider> — Start 中不需要（会自动处理）
• <Outlet> — 渲染匹配的子路由
• <Link> — 类型安全的导航
• <Navigate> — 声明式重定向
• <HeadContent> — 渲染 head 标签（必须放在 <head> 中）
• <Scripts> — 渲染 body 脚本（必须放在 <body> 中）
• <Await> — 使用 Suspense 渲染延迟数据
• <ClientOnly> — 仅在水合后渲染子项
• <CatchBoundary> — 错误边界

Hook 参考

@tanstack/react-router 中的所有 Hook 都可在 Start 中使用：

• useRouter() — 路由器实例
• useRouterState() — 订阅路由器状态
• useNavigate() — 编程式导航
• useSearch({ from }) — 已验证的搜索参数
• useParams({ from }) — 路径参数
• useLoaderData({ from }) — 加载器数据
• useMatch({ from }) — 完整路由匹配
• useRouteContext({ from }) — 路由上下文
• Route.useLoaderData() — 类型化的加载器数据（在路由文件中优先使用）
• Route.useSearch() — 类型化的搜索参数（在路由文件中优先使用）

常见错误

1. CRITICAL：从错误的包导入

// WRONG — this is the SPA router, NOT Start
import { createServerFn } from '@tanstack/react-router'

// CORRECT — server functions come from react-start
import { createServerFn } from '@tanstack/react-start'

// CORRECT — routing APIs come from react-router (re-exported by Start too)
import { createFileRoute, Link } from '@tanstack/react-router'

2. HIGH：在 beforeLoad 或加载器中使用 React Hook

// WRONG — beforeLoad/loader are NOT React components
beforeLoad: () => {
  const auth = useAuth() // React hook, cannot be used here
}

// CORRECT — pass state via router context
const rootRoute = createRootRouteWithContext<{ auth: AuthState }>()({})

3. HIGH：缺少 Scripts 组件

如果根路由的 <body> 中没有 <Scripts />，客户端 JavaScript 就不会加载，应用也无法完成水合。

交叉引用

• @tanstack/start-client-core#start-core — Start 核心概念
• @tanstack/router-core#router-core — 路由基础知识
• @tanstack/react-router#react-router — React Router 钩子和组件