TanStack Start スキル

概要

TanStack Start は TanStack Router 上に構築された フルスタック React フレームワークで、Vite と Nitro (Vinxi 経由) で駆動されています。サーバーサイドレンダリング、ストリーミング、サーバー関数 (RPC)、ミドルウェア、API ルート、および Nitro プリセットを通じてあらゆるプラットフォームへのデプロイメントを提供します。

パッケージ: @tanstack/react-start ルータープラグイン: @tanstack/router-plugin ビルドツール: Vinxi (Vite + Nitro) ステータス: RC (Release Candidate) RSC サポート: React Server Components サポートは開発中であり、非破壊的な v1.x 追加として実装予定

インストール & プロジェクトセットアップ

npx @tanstack/cli create my-app
# または手動でインストール:
npm install @tanstack/react-start @tanstack/react-router react react-dom
npm install -D @tanstack/router-plugin typescript vite vite-tsconfig-paths

プロジェクト構造

my-app/
  app/
    routes/
      __root.tsx          # ルートレイアウト
      index.tsx           # / ルート
      posts.$postId.tsx   # /posts/:postId
      api/
        users.ts          # /api/users API ルート
    client.tsx            # クライアントエントリー
    router.tsx            # ルーター作成
    ssr.tsx               # SSR エントリー
    routeTree.gen.ts      # 自動生成されたルートツリー
  app.config.ts           # TanStack Start 設定
  tsconfig.json
  package.json

設定 (app.config.ts)

import { defineConfig } from '@tanstack/react-start/config'
import viteTsConfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  vite: {
    plugins: [
      viteTsConfigPaths({ projects: ['./tsconfig.json'] }),
    ],
  },
  server: {
    preset: 'node-server', // 'vercel' | 'netlify' | 'cloudflare-pages' | など
  },
  tsr: {
    appDirectory: './app',
    routesDirectory: './app/routes',
    generatedRouteTree: './app/routeTree.gen.ts',
  },
})

サーバー関数 (createServerFn)

サーバー関数は、クライアントとサーバー間の型安全な RPC 呼び出しを提供します。

基本的なサーバー関数

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

// GET (データ取得、キャッシュ可能)
const getUsers = createServerFn()
  .handler(async () => {
    const users = await db.query.users.findMany()
    return users
  })

// POST (ミューテーション、副作用)
const createUser = createServerFn({ method: 'POST' })
  .validator((data: { name: string; email: string }) => data)
  .handler(async ({ data }) => {
    const user = await db.insert(users).values(data).returning()
    return user
  })

Zod バリデーションを使用

import { z } from 'zod'

const updateUser = createServerFn({ method: 'POST' })
  .validator(
    z.object({
      id: z.string(),
      name: z.string().min(1),
      email: z.string().email(),
    })
  )
  .handler(async ({ data }) => {
    // data は完全に型付けされています: { id: string; name: string; email: string }
    return await db.update(users).set(data).where(eq(users.id, data.id))
  })

ミドルウェア

ミドルウェアの作成

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

const loggingMiddleware = createMiddleware().handler(async ({ next }) => {
  console.log('リクエスト開始')
  const result = await next()
  console.log('リクエスト完了')
  return result
})

コンテキストを伴う認証ミドルウェア

const authMiddleware = createMiddleware().handler(async ({ next }) => {
  const request = getWebRequest()
  const session = await getSession(request)

  if (!session?.user) {
    throw redirect({ to: '/login' })
  }

  // ハンドラーに型付きコンテキストを渡す
  return next({ context: { user: session.user } })
})

ミドルウェアのチェーン

const adminMiddleware = createMiddleware()
  .middleware([authMiddleware])
  .handler(async ({ next, context }) => {
    // context.user は authMiddleware から型付けされています
    if (context.user.role !== 'admin') {
      throw redirect({ to: '/unauthorized' })
    }
    return next({ context: { isAdmin: true } })
  })

// 使用方法
const adminAction = createServerFn({ method: 'POST' })
  .middleware([adminMiddleware])
  .handler(async ({ context }) => {
    // context: { user: User; isAdmin: boolean }
    return { success: true }
  })

API ルート (サーバールート)

// app/routes/api/users.ts
import { createAPIFileRoute } from '@tanstack/react-start/api'

export const APIRoute = createAPIFileRoute('/api/users')({
  GET: async ({ request }) => {
    const users = await db.query.users.findMany()
    return Response.json(users)
  },
  POST: async ({ request }) => {
    const body = await request.json()
    const user = await db.insert(users).values(body).returning()
    return new Response(JSON.stringify(user), { status: 201 })
  },
})

SSR ストラテジー

ストリーミング SSR (デフォルト)

export const Route = createFileRoute('/dashboard')({
  loader: async () => ({
    criticalData: await fetchCriticalData(),
    deferredData: defer(fetchSlowData()),
  }),
  component: Dashboard,
})

function Dashboard() {
  const { criticalData, deferredData } = Route.useLoaderData()
  return (
    <div>
      <CriticalSection data={criticalData} />
      <Suspense fallback={<Loading />}>
        <Await promise={deferredData}>
          {(data) => <SlowSection data={data} />}
        </Await>
      </Suspense>
    </div>
  )
}

デプロイメント

サポートされているプラットフォーム (Nitro プリセット)

// app.config.ts
export default defineConfig({
  server: {
    preset: 'node-server',        // 自ホスト Node.js
    // preset: 'vercel',          // Vercel
    // preset: 'netlify',         // Netlify
    // preset: 'cloudflare-pages', // Cloudflare Pages
    // preset: 'aws-lambda',      // AWS Lambda
    // preset: 'deno-server',     // Deno Deploy
    // preset: 'bun',             // Bun
  },
})

ベストプラクティス

1. すべてのサーバー関数入力にはバリデーターを使用する - ランタイムセーフティと TypeScript 推論
2. ミドルウェアを構成する - 認証、ロギング、レート制限などの横断的関心事のため
3. createServerFn GET を使用する - データ取得用 (キャッシュ可能、プリロード可能)
4. createServerFn POST を使用する - ミューテーションと副作用用
5. beforeLoadを使用する - ルートレベルの認証ガード用
6. defer()を使用する - TTFB を改善するための非重要データ用
7. ルーターに defaultPreload: 'intent' を設定する - インスタントナビゲーション用
8. サーバー関数をそれを使用するルートと一緒に配置する

よくある落とし穴

• サーバー関数はクライアント側の変数をクロージャーできません (別々のバンドルに抽出されます)
• サーバー関数から返されるデータはシリアライズ可能である必要があります
• ローダー内で await を忘れるとストリーミングの問題が発生します
• サーバーのみのコードをクライアントバンドルにインポートするとビルドエラーが発生します
• declare module '@tanstack/react-router' がないと型安全性がすべて失われます