tanstack-frontend

TanStack フロントエンドのパターン

概要

プロジェクト標準の TRPC 統合、ローダー戦略、型付き推論、フォーム処理を使用して TanStack Router のルートを実装します。判断ルールについてはこのドキュメントに従い、詳しい例は references/ を参照してください。

基本パターン

1) ローダー主導のデータ戦略でルートを定義する

• 各ルートを createFileRoute(...) で定義し、重要なデータを事前読み込みするローダーを設定します。
• コンポーネント内では、ルートの API（Route.useParams()、Route.useSearch()）からパラメーターや検索条件を読み取ります。
• 例は references/router-loader-examples.md を参照してください。

2) ローダーの事前読み込み戦略を意図的に選択する

• 初回描画に必要なデータには await prefetchQuery(...) を使用します。
• 重要なクエリが複数ある場合は await Promise.all([...]) を使用します。
• 副次的なデータにのみ void prefetchQuery(...) を使用します。
• ローダーのロジックで返されたデータが必要な場合は fetchQuery(...) を使用します。
• void のルールは、以下の Suspense のルールと併せて適用します。

詳しい判断ツリーとパフォーマンス上のトレードオフは references/prefetch-patterns.md を参照してください。

3) void で事前読み込みしたデータには Suspense 境界を設ける

• void prefetchQuery(...) で事前読み込みしたデータを useSuspenseQuery(...) で使用するすべてのコンポーネントを、<Suspense> で囲みます。
• 境界の欠落は任意の最適化ではなく、正確性に関わる不具合（ハイドレーションのリスク）として扱います。
• ルートを確定する前に、void の判断がこの要件を満たしているか確認します。

例とローダーパターンの判断表は references/prefetch-patterns.md を参照してください。

4) TRPC v11 の TanStack Query パターンを適用する

一貫して次のルールに従います。

• TRPC ファクトリーメソッドとともに、TanStack Query のフック（useQuery、useSuspenseQuery、useMutation）を使用します。
• クエリや事前読み込みには .queryOptions(...) を、ミューテーションには .mutationOptions(...) を使用します。
• キャッシュの無効化には .queryKey(...) を使用します。
• TRPC プロシージャで .useQuery() や .useMutation() を呼び出さないでください。

簡潔な使用例と禁止例は references/trpc-v11-query-pattern.md を参照してください。

5) 推論には RouterInputs/RouterOutputs を優先する

• ルートコンポーネントやヘルパー全体で、入力とレスポンスの型付けには RouterInputs/RouterOutputs を優先します。
• UI 専用のビューモデル、外部ライブラリのコントラクト、またはサーバーのペイロードをそのまま反映しない意図的な型の絞り込みや集約を表す場合は、明示的なローカル型を使用できます。
• TRPC のレスポンス形状を手書きのアプリ型として重複定義しないでください。

実践的な推論パターンは references/type-inference.md を参照してください。

6) 生の TanStack Form ではなく、プロジェクトのフォームラッパーを使用する

• このテンプレートでいう「TanStack Form」は、useAppForm と @/shared/forms/* のフィールドコンポーネントとして扱います。
• 共有フォームコンポーネントを組み合わせ、form/field を明示的に渡してフォームを構成します。
• 共有フォームのインフラ自体を更新する場合を除き、機能コードで生の TanStack Form フックを使用しないでください。

検証の例を含むフォームのパターン全体は references/form-patterns.md を参照してください。

7) フロントエンドの規約に従う

• コンポーネントのプロパティ名には type Props = ... 形式を優先します。
• 絶対インポート（@/...）を使用します。
• パッケージ間で共有する型は @project/common からインポートします。
• queryKey(...) ヘルパーを通じて TRPC キャッシュを無効化します。

リソース

references/

• router-loader-examples.md - ルート定義の完全な例
• prefetch-patterns.md - パフォーマンス最適化と事前読み込み戦略
• trpc-v11-query-pattern.md - TRPC v11 のクエリ／ミューテーション／無効化に関する簡潔なルール
• form-patterns.md - 検証例を含むフォーム処理
• type-inference.md - TRPC の型推論パターンと例