react-start

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Start (

@tanstack/react-start

)

React Start (

@tanstack/react-start

)

This skill builds on start-core. Read start-core first for foundational concepts.

This skill covers the React-specific bindings, setup, and patterns for TanStack Start.

CRITICAL: All code is ISOMORPHIC by default. Loaders run on BOTH server and client. Use
createServerFn
for server-only logic.

CRITICAL: Do not confuse
@tanstack/react-start
with Next.js or Remix. They are completely different frameworks with different APIs.

CRITICAL: Types are FULLY INFERRED. Never cast, never annotate inferred values.

本技能基于start-core构建。请先阅读start-core了解基础概念。

本技能涵盖TanStack Start的React专属绑定、搭建流程和使用模式。

重要提示：所有代码默认都是同构的。Loader会同时在服务器和客户端运行。请使用
createServerFn
编写仅服务器端逻辑。

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

重要提示：类型会被完全推导。永远不要对推导的值进行类型断言或手动标注。

Package API Surface

包API范围

@tanstack/react-start

re-exports everything from

@tanstack/start-client-core

plus:

```
useServerFn
```
— React hook for calling server functions from components

All core APIs (

createServerFn

createMiddleware

createStart

createIsomorphicFn

createServerOnlyFn

createClientOnlyFn

) are available from

@tanstack/react-start

Server utilities (

getRequest

getRequestHeader

setResponseHeader

setResponseHeaders

setResponseStatus

) are imported from

@tanstack/react-start/server

@tanstack/react-start

重导出

@tanstack/start-client-core

的所有内容，此外还包括：

```
useServerFn
```
— 用于在组件中调用服务器函数的React钩子

所有核心API（

createServerFn

、

createMiddleware

、

createStart

、

createIsomorphicFn

、

createServerOnlyFn

、

createClientOnlyFn

）都可以从

@tanstack/react-start

获取。

服务器工具函数（

getRequest

、

getRequestHeader

、

setResponseHeader

、

setResponseHeaders

、

setResponseStatus

）需要从

@tanstack/react-start/server

导入。

Full Project Setup

完整项目搭建

1. Install Dependencies

1. 安装依赖

bash

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

bash

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

json

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

json

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

3. tsconfig.json

json

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

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

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

export default defineConfig({
  plugins: [
    tanstackStart(), // 必须在react()之前
    viteReact(),
  ],
})

5. Router Factory (src/router.tsx)

5. 路由工厂 (src/router.tsx)

tsx

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

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
  })
  return 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. Root Route (src/routes/__root.tsx)

6. 根路由 (src/routes/__root.tsx)

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

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. Index Route (src/routes/index.tsx)

7. 首页路由 (src/routes/index.tsx)

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

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钩子

Use

useServerFn

to call server functions from React components with proper integration:

tsx

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

const updatePost = createServerFn({ method: 'POST' })
  .inputValidator((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>
  )
}

使用

useServerFn

可以在React组件中调用服务器函数，并实现良好的集成：

tsx

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

const updatePost = createServerFn({ method: 'POST' })
  .inputValidator((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>
  )
}

Global Start Configuration (src/start.ts)

全局Start配置 (src/start.ts)

tsx

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

tsx

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-Specific Components

React专属组件

All routing components from

@tanstack/react-router

work in Start:

```
<RouterProvider>
```
— not needed in Start (handled automatically)
```
<Outlet>
```
— renders matched child route
```
<Link>
```
— type-safe navigation
```
<Navigate>
```
— declarative redirect
```
<HeadContent>
```
— renders head tags (must be in
```
<head>
```
)
```
<Scripts>
```
— renders body scripts (must be in
```
<body>
```
)
```
<Await>
```
— renders deferred data with Suspense
```
<ClientOnly>
```
— renders children only after hydration
```
<CatchBoundary>
```
— error boundary

来自

@tanstack/react-router

的所有路由组件都可以在Start中使用：

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

Hooks Reference

钩子参考

All hooks from

@tanstack/react-router

work in Start:

```
useRouter()
```
— router instance
```
useRouterState()
```
— subscribe to router state
```
useNavigate()
```
— programmatic navigation
```
useSearch({ from })
```
— validated search params
```
useParams({ from })
```
— path params
```
useLoaderData({ from })
```
— loader data
```
useMatch({ from })
```
— full route match
```
useRouteContext({ from })
```
— route context
```
Route.useLoaderData()
```
— typed loader data (preferred in route files)
```
Route.useSearch()
```
— typed search params (preferred in route files)

来自

@tanstack/react-router

的所有钩子都可以在Start中使用：

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

Common Mistakes

常见错误

1. CRITICAL: Importing from wrong package

1. 重要错误：从错误的包导入

tsx

// 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'

tsx

// 错误——这是SPA路由，不是Start
import { createServerFn } from '@tanstack/react-router'

// 正确——服务器函数来自react-start
import { createServerFn } from '@tanstack/react-start'

// 正确——路由API来自react-router（Start也会重导出）
import { createFileRoute, Link } from '@tanstack/react-router'

2. HIGH: Using React hooks in beforeLoad or loader

2. 严重错误：在beforeLoad或loader中使用React钩子

tsx

// 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 }>()({})

tsx

// 错误——beforeLoad/loader不是React组件
beforeLoad: () => {
  const auth = useAuth() // React钩子，不能在此处使用
}

// 正确——通过路由上下文传递状态
const rootRoute = createRootRouteWithContext<{ auth: AuthState }>()({})

3. HIGH: Missing Scripts component

3. 严重错误：缺少Scripts组件

Without

<Scripts />

in the root route's

<body>

, client JavaScript doesn't load and the app won't hydrate.

如果根路由的

<body>

中没有

<Scripts />

，客户端JavaScript将无法加载，应用也无法完成hydration。

Cross-References

交叉引用

start-core — core Start concepts
router-core — routing fundamentals
react-router — React Router hooks and components

start-core — Start核心概念
router-core — 路由基础
react-router — React Router钩子和组件

react-start

Original

Translation

React Start (@tanstack/react-start)

React Start (@tanstack/react-start)

Package API Surface

包API范围

Full Project Setup

完整项目搭建

1. Install Dependencies

1. 安装依赖

2. package.json

2. package.json

3. tsconfig.json

3. tsconfig.json

4. vite.config.ts

4. vite.config.ts

5. Router Factory (src/router.tsx)

5. 路由工厂 (src/router.tsx)

6. Root Route (src/routes/__root.tsx)

6. 根路由 (src/routes/__root.tsx)

7. Index Route (src/routes/index.tsx)

7. 首页路由 (src/routes/index.tsx)

useServerFn Hook

useServerFn钩子

Global Start Configuration (src/start.ts)

全局Start配置 (src/start.ts)

React-Specific Components

React专属组件

Hooks Reference

钩子参考

Common Mistakes

常见错误

1. CRITICAL: Importing from wrong package

1. 重要错误：从错误的包导入

2. HIGH: Using React hooks in beforeLoad or loader

2. 严重错误：在beforeLoad或loader中使用React钩子

3. HIGH: Missing Scripts component

3. 严重错误：缺少Scripts组件

Cross-References

交叉引用

React Start (
`@tanstack/react-start`
)

React Start (
`@tanstack/react-start`
)