gsap-nextjs

GSAP Next.js

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

マウントとアンマウントは React に属し、その間の5つのフェーズはアニメーションが担います。cacheComponents を使用する場合は、ルートの非表示をアンマウント、再表示を、保持された DOM のマウントとして扱います。

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

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

まずプロジェクトを確認する

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

1. App Router を使用していることを確認します。Pages Router を使用している場合は、このスキルではなく、バージョンに合った Pages Router のガイダンスを使用してください。
2. インストールされている Next.js のバージョンを確認します。記憶に頼るのではなく、node_modules/next/dist/docs/ にある同梱ドキュメントを優先してください。バージョン要件：onNavigate と useLinkStatus（15.3）、<ViewTransition> と transitionTypes（16.2）、cacheComponents 有効時の <Activity> によるルート保持（16.0、オプトイン）。
3. Next の設定で cacheComponents を確認します。これによってルートの保持期間が変わります。

エンジンを選ぶ

インストールされている Next.js のバージョンでサポートされている場合、共有要素のモーフィング、ページのクロスフェード、Suspense の切り替えには React の <ViewTransition> を使用します。ナビゲーションを制御するライブ DOM のアウトロ、割り込み可能なシーケンス、分割テキスト、スクロール連動のモーションには GSAP を使用します。1つの要素につきエンジンは1つにしてください。エンジンの組み合わせを参照してください。

必要な情報だけを読む

• 目に見えないエントランス、初期化の失敗、インデックス作成、初回読み込みのパフォーマンス：初期化と復旧、およびフレームワーク統合。
• 読み込み中／認証時のちらつき、非同期セクションのレイアウト変動：データの準備状態、およびReact のデータ統合。
• ページのイントロとアウトロ、遷移対応リンク、戻る／進む、フォーカス、ルートの切り替え：App Router のナビゲーション。
• 5つのフェーズ、GSAP のセットアップ、React のライフサイクル、表示と非表示、レイアウトの安定性、スクロール、テキスト、プラグイン：ライフサイクルの実装。
• Lenis、ScrollSmoother、またはルート間でイージングされるページスクロール：スムーズスクロール、およびApp Router との統合。
• カーテン、初回訪問時のプリローダー、共有要素のモーフィング：遷移のアーキタイプ、およびApp Router での配置場所。
• タッチ操作、ビューポートの変更、デバイスごとの予算：デバイスと入力。
• 作業完了前の確認：検証。

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

ルール

• セットアップが成功した場合は、見えないイントロを維持します。失敗した場合は、現在の遷移元を復元します。非表示ルールを追加する前に、初期化の契約に従います。
• GSAP はクライアント上でのみ実行します。セレクターのスコープを限定します。すべてのトゥイーン、トリガー、分割、リスナーをクリーンアップします。
• 通常の CSS と安定したラッパーで最終的なジオメトリを確保し、レイアウト領域を二重に増やさずに、遷移元と遷移先のコンテンツを重ねます。
• 構造データの準備ができたら、それぞれの表示対象を表示します。認証やクエリが未解決の状態を、ゲスト状態や空のコンテンツとして扱ってはいけません。
• マウント後に初期値を設定し、その後に描画します。初期化が成功した場合、イントロの前に確定済みのコンテンツが一瞬表示されることはありません。
• 完了時に一時的なスタイルをクリアします。アニメーション中のみ will-change を使用します。これにより、gsap-performance の静的なヒントは上書きされます。
• デバイス層の判定には機能クエリを使います。タッチ状態は解除できるようにし、ホバーなしでもコントロールを操作できるようにします。
• アウトロと終了状態の間は、遷移元のページとコンポーネントをマウントしたまま表示します。アンマウントするか、ルーターに非表示を任せるのは、終了コールバックの後に限ります。
• cacheComponents の場合、ページのライフサイクルは再表示時に再び実行されますが、DOM には確定済みの値がすでに設定されています。ノードが新しいものだと決めつけてはいけません。
• 戻る操作と進む操作では、アウトロを実行しません。イントロのみの経路を用意します。
• ネイティブなリンクの動作、フォーカス、スクロール、JavaScript 無効時の可読性を維持します。
• モーションの低減が有効な場合も同じ確定状態に到達し、すべての完了コールバックを実行します。
• 中断や連続クリック時の動作を定義します。完了処理でナビゲーションの待機を必ず一度だけ解除します。
• 実用的な場合は、実際のブラウザーで確認します。ルート、設定、依存関係、リリースに関する変更では、本番ビルドを使用します。