tanstack-start-architecture

TanStack Start のアーキテクチャ

TanStack Start（@tanstack/react-start）アプリ向けの、移植可能なハウススタイルです。このスキル単独で使用でき、ほかのスキルには依存しません。

目的： UI、フック、機能コードの配置場所、フォルダー／ファイルの命名、所有範囲を定めます。

対象外： Start／Router API の固有仕様、SSR アダプター、デプロイ、最新のフレームワークドキュメントです。これらについては、最新の TanStack Start／Router ドキュメントを参照してください。公式の Start ドキュメントでは、フレームワークは引き続きリリース候補版として説明されています（API は安定していると見なされていますが、バグがないわけではありません）。ほかの場所に残っている古い「alpha」という表記よりも、@tanstack/react-start と @tanstack/react-router の npm latest を優先してください。

対象のリポジトリにすでにアーキテクチャのドキュメント（例：AGENTS.md）があり、内容が競合する場合は、このスキルへの移行をユーザーが求めていない限り、リポジトリの記述を優先します。

スタックのデフォルト設定（コア）

要素	デフォルト
フレームワーク	TanStack Start + ファイルベースの TanStack Router（Vite または Rsbuild）
エントリーポイント	src/router.tsx（getRouter）、routes/__root.tsx、生成される routeTree.gen.ts。start.ts／server.ts は任意
ページ	ページごとにフォルダーと index.tsx を使用（フラットなページリーフは使用しない）
ルート専用コード	ハイフンで始まる同階層のフォルダー（-components、-hooks、-lib）
再利用可能な機能	再利用基準を満たした後に src/modules/<feature>/ を使用
アプリ全体の UI	src/components/
機能以外のインフラストラクチャ	src/lib/
無視プレフィックス	Router の routeFileIgnorePrefix のデフォルトは -

該当するスタックがある場合は、対応する with-* 拡張機能を読み込んでください（以下を参照）。

モード

1. スキャフォールド — checklist.md と tree.md を参照して、新しいページ／レイアウト／機能を作成します。
2. 適用 — 新しい UI／フック／ヘルパーを標準の配置場所に置きます。
3. レビュー — rules.md と照合し、移動を提案します。並行する別のレイアウトは作らないでください。

厳守ルール（コア）

1. すべてのページは segment/index.tsx にします。 フラットなページリーフ（ページコンポーネントファイルとしての billing.tsx など）は追加しないでください。billing/index.tsx を優先してください。
2. ルート専用モジュールには - プレフィックスを付けます（または、アプリで設定されている無視プレフィックスを使用します）。src/routes 内のプレフィックスなしファイルは URL になります。
3. 新しいページ UI は、デフォルトで routes/…/-components に配置します。 ページ専用のフックには -hooks、ヘルパーには -lib を同様に使用します。
4. src/modules/<feature>/ の再利用基準： 2 つ目の利用箇所ができた場合、または複数のルートで使用する明確な共有クライアント／スキーマがある場合に昇格させます。空のモジュールツリーを先回りして作らないでください。
5. モジュールから src/routes をインポートしてはいけません。 ルートからモジュールをインポートすることはできます。
6. モジュールのバレル index.ts は、デフォルトでは作成しません。 具体的なパスからインポートしてください（@/modules/billing/hooks/use-checkout）。
7. アプリ全体のツールキットは src/components/ に、 機能以外のインフラストラクチャは src/lib/ に配置します。共有 UI を無造作に routes/ に置かないでください。
8. URL を変えずにセクションをラップする場合は、 パスレスレイアウトに _name/（または _name.tsx）を使用します。
9. 命名： フォルダー名は名詞／ルートセグメント、リーフ名は短い要素名（billing-page.tsx、use-checkout.ts）にします。フォルダー名で示されている親パスを、すべてのファイル名で繰り返さないでください。
10. ルートフォルダーごとに役割は 1 つです。 そのセグメントのページ／レイアウトと、同階層に置くプライベートコードのみを配置します。

詳細：rules.md、tree.md、examples.md。

必要に応じた開示

必要な内容	参照先
標準的なツリー構成とトークン	references/tree.md
ルールとアンチパターンの適用	references/rules.md
スキャフォールド／レビューのチェックリスト	references/checklist.md
適切なレイアウトと不適切なレイアウト	references/examples.md
任意のスタックオーバーレイ	以下の拡張機能

拡張機能

該当するスタックが存在する場合（またはユーザーから依頼された場合）にのみ拡張機能を読み込みます。 拡張機能はルールを追加します。コアツリーに置き換わるものではありません。

条件	拡張機能
生成された OpenAPI／Hey スタイルのクライアント	with-generated-api-client.md
Better Auth（またはセッション）クライアントモジュール	with-better-auth-client.md
TanStack Query ＋ローダー／queryClient.query	with-tanstack-query.md
パスレス認証／オンボーディング／組織のゲート	with-route-gates.md
TanStack Form ＋モジュール／ルートのスキーマ	with-tanstack-form.md
T3 Env／VITE_ クライアントキー	with-env.md
純粋な認可パッケージ＋クライアントアダプター	with-client-authorization.md
ワークスペース UI パッケージ＋Storybook／トークン	with-ui-package.md
Effect Schema／サーバー専用 Effect	with-effect.md
Vitest — libs／schemas／gates に重点	with-vitest.md