TanStack Start 上手体验：一小时与 Next.js 的对比

npm create @tanstack/start@latest

src/
├── router.tsx
└── routes/
    ├── __root.tsx
    ├── index.tsx
    ├── about.tsx
    └── posts/$postId.tsx

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

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    // params.postId 被推断为 string
    const post = await fetchPost(params.postId)
    return { post }
  },
  component: PostPage,
})

function PostPage() {
  // TypeScript 从 loader 推断出 { post: Post }
  const { post } = Route.useLoaderData()
  return <h1>{post.title}</h1>
}

export const Route = createFileRoute('/dashboard')({
  beforeLoad: async () => {
    const session = await checkAuth()
    if (!session) throw redirect({ to: '/login' })
    return { user: session.user }
  },
  loader: async ({ context }) => {
    // context.user 的类型来自 beforeLoad
    return { data: await fetchDashboard(context.user.id) }
  },
})

import { z } from 'zod'
import { zodValidator } from '@tanstack/zod-adapter'
import { createFileRoute } from '@tanstack/react-router'

const searchSchema = z.object({
  query: z.string().optional(),
  category: z.enum(['electronics', 'clothing', 'books']).optional(),
  page: z.number().default(1),
})

export const Route = createFileRoute('/products')({
  validateSearch: zodValidator(searchSchema),
  component: ProductsPage,
})

// TypeScript 会强制校验参数结构
<Link to="/products" search={{ query: 'keyboard', page: 2 }}>
  搜索
</Link>

function ProductsPage() {
  const { query, category, page } = Route.useSearch()
  // 全部有类型。page 始终是 number（默认值：1）。
}

export const Route = createFileRoute('/products')({
  validateSearch: zodValidator(searchSchema),
  loaderDeps: ({ search }) => [search.page, search.category],
  loader: async ({ deps: [page, category] }) => {
    return fetchProducts({ page, category })
  },
})

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

export const getServerTime = createServerFn().handler(async () => {
  return new Date().toISOString()
})

const time = await getServerTime()

const submitContact = createServerFn({ method: 'POST' })
  .validator((data: { email: string; message: string }) => {
    if (!data.email) throw new Error('Email is required')
    return data
  })
  .handler(async ({ data }) => {
    // data 被推断为 { email: string; message: string }
    await sendEmail(data.email, data.message)
    return { success: true }
  })

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

const authMiddleware = createMiddleware({ type: 'function' })
  .server(async ({ next }) => {
    const session = await getSession()
    if (!session) throw redirect({ to: '/login' })
    return next({ sendContext: { user: session.user } })
  })

// 附加到任意 Server Function
const getProtectedData = createServerFn({ method: 'GET' })
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    // context.user 的类型来自 middleware
    return fetchUserData(context.user.id)
  })

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => fetchPost(params.postId),
  head: ({ loaderData }) => ({
    meta: [
      { title: loaderData.title },
      { name: 'description', content: loaderData.excerpt },
      { property: 'og:title', content: loaderData.title },
      { property: 'og:image', content: loaderData.coverImage },
    ],
  }),
  component: PostPage,
})

// 完整 SSR（默认）：loader + 渲染都在服务端
export const Route = createFileRoute('/page')({
  ssr: true,
})

// 仅数据：loader 在服务端运行，渲染在客户端
export const Route = createFileRoute('/heavy-ui')({
  ssr: 'data-only',
})

// 纯客户端：完全不做 SSR
export const Route = createFileRoute('/dashboard')({
  ssr: false,
})

export const Route = createFileRoute('/reports/$reportId')({
  ssr: ({ search }) => {
    return search.value?.printMode ? true : 'data-only'
  },
})

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

export const Route = createFileRoute('/hello')({
  server: {
    handlers: {
      GET: async () => new Response('Hello from Start'),
    },
  },
  component: HelloPage,
})

// 路由级别的默认配置
const router = createRouter({
  routeTree,
  defaultPreload: 'intent', // hover/touch
  defaultPreloadStaleTime: 30_000,
})

// 单个链接覆盖
<Link to="/posts/$postId" params={{ postId: '1' }} preload="viewport">
  查看文章
</Link>

// TanStack Start：缓存是路由定义的一部分
export const Route = createFileRoute('/posts')({
  loader: () => fetchPosts(),
  staleTime: 5_000,        // 数据 5 秒内保鲜
  preloadStaleTime: 30_000, // 预加载数据 30 秒内保鲜
})

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

export default defineConfig({
  plugins: [tanstackStart(), nitro({ preset: 'cloudflare-workers' })],
})

export const Route = createFileRoute('/posts/$postId')({
  errorComponent: ({ error, reset }) => (
    <div>
      <p>加载文章失败：{error.message}</p>
      <button onClick={reset}>重试</button>
    </div>
  ),
})