gsap-react-router

GSAP React Router

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

マウントとアンマウントは React が担い、その間の 5 つのフェーズはアニメーションが担います。React Router に離脱フックはありません。ブロッカーでナビゲーションを保留するか、開始前にインターセプトしてください。パラメーターが変わっても、ルート要素が再利用されることがあります。

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

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

プロジェクトの調査から始める

リポジトリの指示、既存のアニメーション、レイアウト、ナビゲーション、CSS、アクセシビリティの規約、チェック項目を確認してください。そのうえで、次の手順を実施します。

1. React Router 7 以降であることと、そのモードを確認します。フレームワークモードでは、react-router.config.ts、routes.ts、root.tsx、および entry.client.tsx の HydratedRouter を使用します。データモードでは、createBrowserRouter と RouterProvider を使用します。宣言的モードでは、BrowserRouter を使用し、ローダー、useNavigation、ブロッカーはありません。Remix 2 アプリでは、@remix-run/react の同じフックを使用します。その場合は、その旨を伝え、名前を対応付けてください。
2. インストール済みバージョンを node_modules/react-router/package.json から読み取ります。パッケージには docs/、CHANGELOG.md、.d.ts ファイルが dist/ に含まれています。記憶よりも、これらを優先してください。バージョン要件：useBlocker（6.19）、viewTransition と useViewTransitionState（6.27）、Link mask と useTransitions（7.15）、ミドルウェア（7.9 では future.v8_middleware の背後で有効、8 では常時有効）。バージョン 8 は ESM 専用で、React 19.2 が必要です。また、react-router-dom は廃止され、RouterProvider と HydratedRouter は react-router/dom からインポートします。
3. フレームワークモードでは、react-router.config.ts の ssr と prerender を確認します。サーバーでレンダリングされるページと事前レンダリングされるページは、ハイドレーション前に HTML を描画します。ssr: false では、ルートルートとその HydrateFallback だけを含む index.html が配信されるため、ルートコンテンツはハイドレーション後にレンダリングされ、描画前のルールは不要です。サーバーレンダリングなしのデータモードと宣言的モードも同様です。

エンジンを選ぶ

データモード／フレームワークモードでは、スナップショットのモーフィングやページのクロスフェードに、viewTransition を指定した Link、Form、または navigate を使用します。ナビゲーションを保留する実 DOM のアウトロ、中断可能なシーケンス、分割テキスト、またはスクロール連動モーションには GSAP を使用します。要素ごとにエンジンは 1 つにしてください。エンジンの併用を参照してください。

必要な情報だけを読む

• 見えない入口、初期化の失敗、インデックス作成、初回読み込みのパフォーマンス：初期化と復旧、およびフレームワーク統合。
• ブロッカーのアウトロ、遷移を考慮したリンク、ロック、保留状態、戻る／進む、切り替え時の隙間、スクロール、フォーカス、View Transitions：React Router ナビゲーション。
• モードとそのフック、ルートの再利用と再マウント、レイアウトと<Outlet>、SSR と SPA モードの初回描画、ストリーミング、フェッチャー、モーダルルート：ルートのライフタイム。
• 5 つのフェーズ、GSAP のセットアップ、React のライフサイクル、表示と非表示、レイアウトの安定性、スクロール、テキスト、プラグイン：ライフサイクルの実装。
• Lenis、ScrollSmoother、またはルート間でイージングするページスクロール：スムーズスクロール、およびReact Router 統合。
• カーテン、初回訪問時のプリローダー、共有要素のモーフィング：遷移のアーキタイプ、およびReact Router での配置場所。
• タッチ、ビューポートの変更、デバイスの予算：デバイスと入力。
• 作業完了とする前に：検証。

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

ルール

• セットアップ成功時は、非表示のイントロを維持します。失敗時は、現在の受信側のオーナーを復元します。非表示ルールを追加する前に、初期化の契約に従ってください。
• GSAP はブラウザーでのみ実行されます。フレームワークモードではルートモジュールがサーバー上で評価されるため、GSAP の呼び出しは useGSAP またはエフェクト内に、登録は .client の副作用モジュール内に記述してください。パッケージから gsap と useGSAP をインポートしてください。SSR 中は .client のエクスポートが未定義になります。セレクターのスコープを限定してください。すべてのトゥイーン、トリガー、分割、リスナーをクリーンアップしてください。
• 通常の CSS と安定したラッパーで最終的なジオメトリを確保し、レイアウト領域を二重に使わずに、退出するコンテンツと入ってくるコンテンツを重ねます。
• マウントしてから初期値を設定し、その後に描画します。サーバー HTML はハイドレーション前に描画されます。ルート Layout のインラインスクリプトで設定するルート属性のもとで、初期フェーズ中に限りイントロ対象を非表示にし、JavaScript が無効な場合の経路も用意してください。
• 状態が確定したら一時的なスタイルを解除します。アニメーション中のみ will-change を使用してください。これは gsap-performance の静的なヒントを上書きします。
• デバイスの階層には機能クエリを使用してください。タッチ状態は解除できるようにし、コントロールはホバーなしでも動作させてください。
• アウトロと終了状態の間、退出するルートをマウントしたまま表示しておきます。ルーターは新しいルートのコミット時に古いルートをアンマウントするため、コミットを保留してください。終了コールバックから useBlocker と proceed() を使うか、Link のデフォルト動作を防いで、アウトロ後に navigate します。
• POP をブロックしたり、アウトロを実行したりしないでください。戻る・進む操作では、スクロール復元後に初期状態とイントロだけを適用します。
• 新しいパラメーターで同じルートに移動すると、要素は再利用されます。location.pathname をキーにして outlet を再生成するか、確定済みの値がすでに設定されている DOM に対して、pathname の依存関係からライフサイクルを再実行してください。
• ローダーは proceed() の後に実行されるため、終了状態はデータを待ちます。操作の意図に応じてプリフェッチし、入ってくる対象の準備が整うまでルートコンテナーを覆ってください。
• フェッチャーはナビゲーションではありません。fetcher.state をページ遷移として扱わないでください。
• 要素ごとにエンジンは一つだけにしてください。名前付きビュー遷移と GSAP のトゥイーンを同じノードに適用すると、互いに競合します。
• ネイティブのリンク動作を維持してください。修飾キー付きクリック、target、reloadDocument、外部 URL、prefetch、NavLink の状態、フォーカス、スクロール、JavaScript が無効な場合の可読性を保ちます。
• モーションの軽減設定でも同じ確定状態に到達し、proceed() を呼び出すコールバックを含む、すべての完了コールバックを引き続き実行します。
• 割り込みと連続クリックの動作を定義してください。完了時にナビゲーション待ちを必ず一度だけ解除します。
• 可能な場合は実際のブラウザーで検証してください。ルート、設定、依存関係、またはリリースに関する変更には、本番ビルドを使用してください。