vue-start

Vue Start（@tanstack/vue-start）

このスキルは start-core を基盤としています。基礎概念については、まず @tanstack/start-client-core#start-core をお読みください。

このスキルでは、TanStack Start の Vue 固有のバインディング、セットアップ、パターンを扱います。

CRITICAL：すべてのコードはデフォルトで ISOMORPHIC です。ローダーはサーバーとクライアントの両方で実行されます。サーバー専用のロジックには 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：script ブロック内で .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 設定で Start プラグインより前に Vue プラグインを配置する

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

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

5. HIGH：Html／Body を誤って使用する

Vue Start では、SSR ドキュメントシェルに <Html> と <Body> コンポーネントを使用します。サーバーでは <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 のコンポーザブルとコンポーネント