tanstack-start-conventions

TanStack Start の規約

この組織の TanStack Start アプリ向けのスタック規約です。必須スキル tanstack-router-conventions（検索パラメーター、きれいな URL、ローダーと Query、フォームと useMutation の使い分け、型付き Router TS、開発者ツール）を参照してください。ここでは重複させないでください。認証とセッションのレイアウトについては、tanstack-start-auth と併用してください。

参照するドキュメント

タスク	ファイル
app/src フォルダーの作成またはリファクタリング、薄いルート、Layout/Page の命名、テスト	app-structure.md
.server.ts / .functions.ts 間のコード分割、インポート保護、beforeLoad と loader の使い分け、エラーログ	client-server-boundaries.md
createServerFn、バリデーション、フォーム送信、無効化	server-functions.md
ローダーまたはコンポーネントが DB/fs/シークレットにアクセスする場合、クライアントナビゲーションのバグ	execution-model.md
ルートの ssr 設定、SSR / ハイドレーションのデバッグ、Query のデハイドレーション	selective-ssr.md
routes/api/ 配下の API ルート（パスパラメーター、検索、POST 本文）	params-search-api-routes.md
実験的な RSC（renderServerComponent、createCompositeComponent）	server-components.md
Vite + Nitro スクリプト用の bun --bun	local-runtime.md

認証フロー：スキル tanstack-start-auth。

譲れないルール

トピック	ルール
サーバー専用モジュール	*.server.ts - ルート／コンポーネントからインポートしないでください（例外：routes/api/ およびコンポーネントを持たないハンドラー専用ルート）。内部では createServerOnlyFn を使用してください
クライアントから呼び出し可能	createServerFn を使用する *.functions.ts。エクスポート名は *Fn にしてください
公開サーバー関数	public*.functions.ts - グローバルな認証ミドルウェアは使用しないでください。レート制限／トークンチェックは .server.ts で行ってください（tanstack-start-auth を参照）
API ルートファイル	ルートファイルに server-only インポートマーカーを付けないでください。サーバー専用ロジックはハンドラー内、またはツリーシェイキングされるインポート内に配置してください
API 検索パラメーター	API ルートで validateSearch を使用しないでください。request.url から GET 内で Zod の safeParse を実行し、失敗時は 400 の JSON を返してください
SSR	すべてのルートで ssr を明示的に設定してください。UI の既定値は true、ハンドラー専用の API ルートは false、マップを多用する UI は 'data-only' です
ローカルの Bun ランタイム	Vite の dev と Nitro の start／preview では bun --bun を使用してください
Router の検索／Query	tanstack-router-conventions が担当します（parseSearch／stringifySearch、loader + Query）

すぐに決めるための指針

• beforeLoad と loader： リダイレクト、認証、軽量なコンテキストは beforeLoad（ミドルウェアではありません）で処理し、データ取得／Query の事前設定は loader で行います。beforeLoad は検索パラメーターの変更を含め、ナビゲーションのたびに再実行されるため、頻繁に更新されるルート（マップのビューポート、レイヤー切り替え）ではリダイレクト／認証／地域情報を loader に配置し、それらのパラメーターを loaderDeps に含めないでください。詳細：client-server-boundaries.md。
• Loader と Query、フォームとミューテーション： tanstack-router-conventions -> references/router-and-query.md（#client-mutations）に従ってください。Start では、loader と mutationFn が *Fn を呼び出します。サーバーとの I/O は必ず createServerFn を経由してください。
• ssr： サーバー認証／データを必要とする、マップ／キャンバスを多用する UI には 'data-only' を指定します。ハンドラー専用の API（server.handlers）には false を指定します。完全にクライアントファーストの UI ルートには false を指定します（まれです）。
• サーバーコンポーネント： オプトイン方式の実験的機能であり、FMC のデータ処理経路では既定で使用しません。

関連スキル

トピック	スキル
Router（必須）	tanstack-router-conventions
認証／セッション	tanstack-start-auth
Bun のインストール／nvm	tech-stack -> bun-install
Zustand	zustand-state-management
TanStack Router を使わない URL 状態	nuqs
リファクタリング後の残りの配置先	unslop-code Phase 6 -> references/component-location.md