gsap-tanstack-router

GSAP TanStack Router

マウント → 初期状態 → イントロ → 安定状態 → アウトロ → 最終状態 → アンマウント

マウントとアンマウントは React が担い、その間の 5 つのフェーズはアニメーションが担います。TanStack Router は共有レイアウトを保持し、パラメーターの変更時にルートを再利用できます。また、保留中の UI やローダーも新しいページが表示されるタイミングに影響します。

求められている見た目と、既存プロジェクトの規約を維持してください。必要に応じて GSAP／プラグインを追加します。依頼がない限り、選択済みのアニメーションライブラリを置き換えないでください。

このスキルでは、モーションを実行するタイミングを決めます。何を動かすか、また高級感や遊び心といった雰囲気を表現する方法については、animaxxing スキルがインストールされている場合はそれも読み込んでください。そのレシピと雰囲気を見つけるためのガイドは、このライフサイクルに組み込めます。

プロジェクトから始める

リポジトリの指示、既存のアニメーション、レイアウト、ナビゲーション、CSS、アクセシビリティの規約、チェック項目を確認します。その後、次の手順に進みます。

1. @tanstack/react-router を確認します。Next.js の場合は gsap-nextjs、React Router の場合は gsap-react-router、ルーターを使わない React の場合は gsap-react を使用します。Solid Router は対象外です。
2. インストールされている @tanstack/react-router のバージョンを確認し、@tanstack/react-start がある場合はそのバージョンも確認します。記憶に頼るのではなく、同梱の型定義を優先してください。RouterOptions、RouterState、RouterEvents については node_modules/@tanstack/router-core/dist/esm/router.d.ts、ブロッカーについては node_modules/@tanstack/react-router/dist/esm/useBlocker.d.ts、履歴アクションについては node_modules/@tanstack/history/dist/esm/index.d.ts を参照します。TanStack/router リポジトリの docs/router/ と docs/start/ が信頼できる情報源です。読み込みのアーキテクチャは 1.16x および 1.17x リリースで変更されました。RouterState.isTransitioning は router-core 1.171.2x では削除されており、useBlocker は現在も実験的機能としてマークされています。
3. ファイルベースのルート（createFileRoute、routeTree.gen.ts、__root.tsx）と、コードベースのルート（createRoute、createRootRoute）を見分けます。ライフサイクルは同じで、異なるのはルートオプションの配置場所だけです。
4. TanStack Start（SSR、HeadContent と Scripts を含むルートドキュメントシェル）と、クライアントのみの Vite アプリ（RouterProvider を div にレンダリング）を見分けます。クライアントのみのアプリは React の前に何も描画しないため、描画前のルールは不要です。ルートごとの ssr、defaultSsr、spa.enabled、プリレンダリングを確認します。
5. ルーターのオプションを確認します。defaultPreload、defaultPendingComponent、defaultPendingMs、defaultPendingMinMs、defaultViewTransition、scrollRestoration、defaultStaleTime、defaultRemountDeps です。それぞれ、ページがマウントされるタイミングや、読み込み中にユーザーに表示される内容を変えます。

エンジンを選ぶ

スナップショットの変形やページのクロスフェードには、defaultViewTransition または Link／navigate の viewTransition を使用します。ナビゲーションを制御するライブ DOM のアウトロ、中断可能なシーケンス、分割テキスト、スクロール連動のモーションには GSAP を使用します。各要素で使用するエンジンは 1 つにしてください。エンジンの併用を参照してください。

必要な情報だけを読む

• 目に見えない入口、初期化の失敗、インデックス作成、初回読み込みのパフォーマンスについては、初期化と復旧と、フレームワーク統合を参照してください。
• ルーター API と 1 回のナビゲーションの順序、useBlocker またはインターセプトされた Link によるナビゲーション前のアウトロ、ロック、戻る／進む、保留中の UI、切り替え時の隙間、スクロール、フォーカス、View Transitions については、TanStack ナビゲーションを参照してください。
• ルートの再利用と remountDeps の違い、レイアウトと Outlet、GSAP の React ライフサイクル、条件付きコンテンツ、TanStack Start の SSR とハイドレーション、遅延データについては、ルートのライフタイムを参照してください。
• 5 つのフェーズ、GSAP のセットアップ、表示と非表示、レイアウトの安定性、スクロール、テキスト、プラグインについては、ライフサイクルの実装を参照してください。
• Lenis、ScrollSmoother、またはルートをまたぐイージング付きページスクロールについては、スムーズスクロールと、TanStack との統合を参照してください。
• カーテン、初回訪問時のプリローダー、共有要素のモーフィングについては、トランジションのパターンと、TanStack Router での配置場所を参照してください。
• タッチ、ビューポートの変更、デバイスの予算については、デバイスと入力を参照してください。
• Tauri、Electron、Wails のデスクトップシェルについては、デスクトップ WebViewを参照してください。
• 作業完了とする前に、検証を参照してください。

このリポジトリと併せて、公式 GSAP スキルをインストールしてください。API の詳細を確認するには gsap-core を、コンポーネントのセットアップを確認するには gsap-react を、必要に応じて読み込んでください。

ルール

• 初期化が成功した場合は非表示のイントロを維持し、失敗した場合は現在の受信側オーナーを復元します。非表示ルールを追加する前に、初期化の契約に従ってください。
• GSAP はクライアントでのみ実行されます。useGSAP はサーバーで実行されません。Start がサーバーでレンダリングするファイルでは、モジュールスコープで GSAP を呼び出さないでください。セレクターのスコープを限定してください。すべてのトゥイーン、トリガー、分割、リスナーをクリーンアップしてください。
• 通常の CSS と安定したラッパーで最終的なジオメトリを確保し、レイアウト領域が二重にならないよう、退出するコンテンツと入ってくるコンテンツを重ねてください。
• マウントし、初期値を設定してから、描画します。初期化が成功した場合、イントロの前に確定済みのコンテンツが一瞬表示されることはありません。Start ではハイドレーション前にサーバーの HTML が描画されるため、初期フェーズ中のみ、ScriptOnce のインラインスクリプトが設定するルート属性の下でイントロの対象を非表示にし、JavaScript が無効な場合の経路も用意してください。
• 確定状態では一時的なスタイルをクリアしてください。will-change はアニメーション中のみ使用してください。これは gsap-performance の静的なヒントを上書きします。
• デバイスの階層判定には機能クエリを使用してください。タッチ状態は解除されるようにし、ホバーなしでもコントロールを操作できるようにしてください。
• 退出するページは、アウトロと終了状態を通じてマウントされたまま、表示し続けてください。ルーターは、すべてのブロッカーがナビゲーションを許可し、ローダーの処理が完了した後にのみ切り替わります。終了コールバックからブロッカーを解決してください。
• URL が変わる前にルーターイベントは発生しません。onBeforeNavigate は履歴の確定後に実行され、確定前に実行されるのはブロッカーだけです。
• 新しいパラメーターで同じルートに移動した場合、コンポーネントは再利用されます。パラメーターをキーにして、確定済みの値をすでに持つ DOM に対してライフサイクルを再実行するか、remountDeps を設定してください。
• 戻る・進むでは、action が BACK、FORWARD、または GO となって到着します。これらにアウトロを実行しないでください。ブロッカーの実行時には、すでに URL が移動しています。スクロール復元後にイントロのみを実行する経路を用意してください。
• ロード開始時、つまり新しいページがマウントされる前に、useLocation は遷移先へ移動します。ルートコンテンツのキーに使用せず、表示中のマッチ、または resolvedLocation をキーにしてください。
• ネイティブリンクの動作、プリロード、activeProps、フォーカス、スクロール、JavaScript が無効な場合の可読性を維持してください。
• 動きを抑制する設定でも同じ確定状態に到達し、ブロック中のナビゲーションを続行させるものも含め、すべての完了コールバックを引き続き実行してください。
• 中断と連続クリック時の動作を定義してください。完了時には、ナビゲーション待機を必ず一度だけ解除してください。
• 可能な場合は実際のブラウザーで確認してください。ルート、設定、依存関係、リリースに関する変更では、本番ビルドを使用してください。