vue-start

Vue Start（@tanstack/vue-start）

此技能基于 start-core。请先阅读 @tanstack/start-client-core#start-core，了解基础概念。

此技能介绍 TanStack Start 的 Vue 专用绑定、设置和模式。

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

CRITICAL：不要将 @tanstack/vue-start 与 Nuxt 混淆。它们是完全不同的框架，API 也不同。

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

包 API 一览

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

• useServerFn — 用于在组件中调用服务端函数的 Vue 组合式函数

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

服务端工具（getRequest、getRequestHeader、setResponseHeader、setCookie、getCookie）从 @tanstack/vue-start/server 导入。

完整项目设置

1. 安装依赖

npm i @tanstack/vue-start @tanstack/vue-router vue
npm i -D vite @vitejs/plugin-vue @vitejs/plugin-vue-jsx typescript

2. package.json

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

3. tsconfig.json

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "vue",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}

4. vite.config.ts

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/vue-start/plugin/vite'
import vuePlugin from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'

export default defineConfig({
  plugins: [
    tanstackStart(), // MUST come before vue plugin
    vuePlugin(),
    vueJsx(), // Required for JSX/TSX route files
  ],
})

5. 路由器工厂（src/router.tsx）

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

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

6. 根路由（src/routes/__root.tsx）

import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
  Html,
  Body,
} from '@tanstack/vue-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 (
    <Html>
      <head>
        <HeadContent />
      </head>
      <Body>
        <Outlet />
        <Scripts />
      </Body>
    </Html>
  )
}

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

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

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

const HomePage = defineComponent({
  setup() {
    const greeting = Route.useLoaderData()
    return () => <h1>{greeting.value}</h1>
  },
})

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

useServerFn 组合式函数

使用 useServerFn 在 Vue 组件中调用服务端函数，并自动处理重定向：

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

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

// In a component setup:
const updatePostFn = useServerFn(updatePost)
const title = ref('')

async function handleSubmit(postId: string) {
  await updatePostFn({ data: { id: postId, title: title.value } })
}

与 React 版本不同，useServerFn 不会用 useCallback 包装返回的函数——Vue 的 setup() 在每个组件实例中只运行一次，因此无需记忆化。

Vue 专用组件

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

• <Outlet> — 渲染匹配的子路由
• <Link> — 使用作用域插槽进行类型安全的导航
• <Navigate> — 声明式重定向
• <HeadContent> — 渲染 head 标签（必须放在 <head> 中）
• <Scripts> — 渲染 body 脚本（必须放在 <body> 中）
• <Await> — 使用 Vue <Suspense> 渲染延迟加载的数据
• <ClientOnly> — 仅在 onMounted 后渲染子元素
• <CatchBoundary> — 通过 onErrorCaptured 实现错误边界
• <Html> — SSR 外壳的 <html> 包装器
• <Body> — SSR 外壳的 <body> 包装器

组合式函数参考

@tanstack/vue-router 中的所有组合式函数都可在 Start 中使用。大多数函数会返回 Ref<T>，请通过 .value 访问：

• useRouter() — 路由器实例（不是 Ref）
• useRouterState() — Ref<T>，订阅路由器状态
• useNavigate() — 导航函数（不是 Ref）
• useSearch({ from }) — Ref<T>，经过验证的搜索参数
• useParams({ from }) — Ref<T>，路径参数
• useLoaderData({ from }) — Ref<T>，加载器数据
• useMatch({ from }) — Ref<T>，完整的路由匹配信息
• useRouteContext({ from }) — Ref<T>，路由上下文
• Route.useLoaderData() — Ref<T>，类型化的加载器数据（在路由文件中优先使用）
• Route.useSearch() — Ref<T>，类型化的搜索参数（在路由文件中优先使用）

常见错误

1. CRITICAL：从错误的包导入

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

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

// CORRECT — routing APIs come from vue-router
import { createFileRoute, Link } from '@tanstack/vue-router'

2. CRITICAL：忘记在脚本块中使用 .value

大多数组合式函数会返回 Ref<T>。在 <script> 中，请通过 .value 访问。

// WRONG
const data = Route.useLoaderData()
console.log(data.message) // undefined!

// CORRECT
const data = Route.useLoaderData()
console.log(data.value.message)

3. HIGH：缺少 Scripts 组件

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

4. HIGH：在 Vite 配置中将 Vue 插件放在 Start 插件之前

// WRONG
plugins: [vuePlugin(), tanstackStart()]

// CORRECT
plugins: [tanstackStart(), vuePlugin()]

5. HIGH：错误使用 Html/Body

Vue Start 使用 <Html> 和 <Body> 组件作为 SSR 文档外壳。在服务端，它们会渲染 <html> 和 <body> 标签；在客户端，它们会妥善处理水合。

// WRONG — plain HTML tags can cause hydration mismatches
function RootComponent() {
  return (
    <html>
      <body>
        <Outlet />
      </body>
    </html>
  )
}

// CORRECT — use Html and Body components
function RootComponent() {
  return (
    <Html>
      <head>
        <HeadContent />
      </head>
      <Body>
        <Outlet />
        <Scripts />
      </Body>
    </Html>
  )
}

交叉引用

• @tanstack/start-client-core#start-core — Start 核心概念
• @tanstack/router-core#router-core — 路由基础知识
• @tanstack/vue-router#vue-router — Vue Router 组合式函数和组件