tanstack-start

TanStack Start (React) — RC 対応プレイブック

TanStack Router 上で動作するフルスタック React です。ルートごとの SSR/CSR、ファイルベースルーティング、サーバー関数に対応し、Cloudflare Workers を第一級でサポートします。

このスキルを使う場面

• ルート単位で SSR/CSR/SSG を切り替える必要がある、新規 React アプリを構築するとき。
• ファイルベースルーティングと API ルートを維持しながら、Next.js/React Router から移行するとき。
• 型付きサーバー関数とバインディングを使って、エッジランタイム（Workers）にデプロイするとき。
• 型安全なパラメーターと検索パラメーター、組み込みの事前読み込みによる予測可能なルーティングが必要なとき。

内容

• リファレンス：クイックスタート／レイアウト、レンダリングモード、サーバー関数、Cloudflare ホスティング、実行／認証に加え、新しいルーティング／データ／ナビゲーション／開発者ツールのガイド。
• スクリプト：scripts/bootstrap-cloudflare-start.sh <app> は Start + Workers + バインディング型をスキャフォールドします。
• トラブルシューティング：ハイドレーション、API ルーティング、バインディング、ナビゲーション／事前読み込みの失敗。

---

クイックスタート（React）

npm create @tanstack/start@latest my-app
cd my-app
npm run dev

手動インストール（すべてのバンドルターゲットに対応）：公式のインストールガイドに従って、バンドラープラグイン（vite、webpack、または esbuild）とともに @tanstack/react-router + @tanstack/react-start を追加します。

コアレイアウトの確認

• app/routes/** のファイルベースルート → ルーターツリー、自動コード分割 + データの事前読み込み。
• app/entry.client.tsx は <StartClient /> をハイドレーションし、app/entry.server.tsx は createServerEntry でラップします。
• app/config.ts または app/start.ts で defaultSsr、spaMode、ミドルウェア、コンテキストを設定します。

---

ルーティング + データのベストプラクティス

• 型安全なパラメーターと検索パラメーター：createFileRoute() がパスパラメーターを推論します。検索パラメーターを解析および型変換するには、validateSearch（zod）を追加します。
• ルートのマッチング順序は決定的です（index → static → dynamic → splat）。キャッチオールを追加するときは、この順序を前提にしてください。
• ローダーはロケーションが変わるたびに一度実行されます。プレーンなデータを返し、制御フローには redirect()／notFound() をスローします。
• データの変更：action／サーバー関数を同じ場所に配置し、ローダーは読み取り専用にします。変更後は router.invalidate() で無効化します。
• TanStack Query ブリッジ：ルーターコンテキストで QueryClient を作成し、ローダー内で ensureQueryData を使ってフェッチを重複排除します。
• 遅延／外部データ：部分データをストリーミングするか、外部ローダーから読み取ります。サスペンスに対応したレスポンスを優先します。
• ヘッド管理：各ルートで head を設定して <title>／メタデータを指定します。ローダーデータから導出し、SEO の一貫性を保ちます。
• Not Found／認証：ローダー／ミドルウェアで notFound() または redirect() をスローします。UX にはエラーバウンダリーを使用します。

ルートの例（型付き検索パラメーター + データのみの SSR）：

// app/routes/posts.$postId.tsx
import { createFileRoute, redirect } from '@tanstack/react-router'
import { z } from 'zod'

export const Route = createFileRoute('/posts/$postId')({
  validateSearch: z.object({ preview: z.boolean().optional() }),
  ssr: 'data-only',
  loader: async ({ params, search, context }) => {
    const post = await context.queryClient.ensureQueryData(['post', params.postId], () =>
      fetch(`/api/posts/${params.postId}?preview=${!!search.preview}`).then(r => r.json())
    )
    if (!post.published && !search.preview) throw redirect({ to: '/drafts' })
    return { post }
  },
})

---

ナビゲーション、事前読み込み、UX

• リンクの事前読み込みのデフォルト：<Link preload="intent">（ホバー／フォーカス）でルートデータ／コードを事前読み込みします。ファーストビューに表示されるルートには preload="render" を使います。
• プログラムによる事前読み込み：router.preloadRoute({ to, search }) を使い、ナビゲーション前にキャッシュをウォームアップします（例：表示されたとき）。
• ルートのマスキング：ユーザーにわかりやすいマスクを表示しながら、正規 URL を維持します（例：/products?slug=abc を /p/abc としてマスキング）。
• ナビゲーションのブロック：router.navigate({ to, replace, from }) のブロッカーまたは useBlocker で、未保存のフォームを保護します。
• スクロール位置の復元：scrollRestoration を有効にして、戻る／進むときにスクロール位置を復元します。長いリストを使う場合は、ルートごとにカスタマイズします。
• 検索パラメーターのシリアライズ：解析／文字列化をカスタマイズし、数値／日付を安定して扱い、文字列化されたブール値を避けます。

---

レンダリングとパフォーマンス

• ルートごとの SSR：ルートに ssr: true | false | 'data-only' を設定します。defaultSsr 設定で基本値を指定します。
• コード分割：ファイルベースルートは自動で分割されます。コードベースのルートで手動チャンクを追加するには、lazy／load を使います。
• 事前読み込み戦略：preload="intent" のリンクと defaultPreloadStaleTime を組み合わせ、過剰なフェッチを防ぎます。
• レンダリングの最適化：ローダーを純粋に保ち、重いコンポーネントをメモ化し、CSR ルートでは pendingComponent を使ってレイアウトシフトを防ぎます。

---

開発ツール、Lint、LLM サポート

• 開発中に <RouterDevtools /> を追加して、マッチ、ローダーの状態、プリロードを調べます。
• ESLint プラグイン @tanstack/eslint-plugin-router を推奨設定で有効にし、型推論に影響するプロパティの順序（例：beforeLoad を loader より前に配置）を適用します。
• LLM 対応ルーティング：Router は構造化されたルートメタデータを LLM エージェントに公開します。AI によるナビゲーションを改善するため、Route のメタデータの説明は簡潔に保ちます。

---

デプロイに関する注意事項（Cloudflare 向け）

• バインディングがサーバーエントリに届くよう、Vite プラグインでは cloudflare({ viteEnvironment: { name: 'ssr' } }) を最初に配置します。
• 変更後にバインディングを再生成します：npm run cf-typegen。
• 静的コンテンツが中心のサイトでは、プリレンダリングを有効にして HTML を Workers Assets/Pages に配信します。パラメーター付きルートを除外するか、明示的に pages を追加します。

---

リリース前チェックリスト

• ルートがハイドレーション警告なしで読み込まれること（非決定的な UI には ssr: 'data-only' を推奨します）。
• 検索パラメーターが validateSearch で検証され、必要に応じてカスタムシリアライザーが設定されていること。
• トラフィックの多いルートでリンクのプリロードが設定され、未保存のフォームにはブロッカーが追加されていること。
• ESLint プラグインが有効になっており（create-route-property-order ルール）、npm run check が成功すること。
• Devtools をローカルで確認し、router.matches の状態が正しいこと。
• Cloudflare バインディングの型が定義され（cf-typegen）、ストリーミングが curl -N でテストされていること。