Next.js ページ＆ルート開発 (nextjs-page-dev)
非同期ルートパラメータ、ローカライズ翻訳辞書、動的メタデータ、型安全なJSON-LD構造化データ（schema-dts）、静的プリレンダリングを備えた、本番環境対応のNext.js App Routerページを作成するための専門ワークフローです。
[!TIP] モジュールアセットと詳細ガイド:
- ストリーミングとUI境界:
references/streaming-and-boundaries.md- ページ規約とライフサイクル:
references/page-conventions-and-lifecycle.md- SEOと構造化データガイド:
references/seo-structured-data-guide.md- 再利用可能テンプレート:
resources/templates/- 検証スクリプト:
scripts/verify-page.ps1(Windows) /scripts/verify-page.sh(Linux)
アーキテクチャルールと標準
1. 計画コンテキストとルートレジストリ
docs/project.jsonを読み込み、supported_languages、dictionaries_dir（デフォルト:"messages"）、new_component_dirを解決します。- すべてのナビゲーションURLは
@/lib/routesまたは@/i18n/navigationのROUTESを参照する必要があります。 - 対象ページのパス階層:
app/[locale]/<route-path>/page.tsx（ローカライズされていない場合はapp/<route-path>/page.tsx）。
2. ゼロハードコーディングと辞書への入力
- ハードコードされたコピーは禁止: ページの見出し、タイトル、説明、静的ラベルは、JSXを記述する前に、すべての
supported_languagesのmessages/[locale].jsonに追加する必要があります。 - RSC翻訳: Server Components で
await getTranslations('<namespace>')を使用して翻訳を読み取ります。
3. SEO、メタデータ、JSON-LD
- 動的メタデータ:
generateMetadata({ params, searchParams }: Props)をエクスポートし、動的なtitle、description、および正規URL（alternates: { canonical: ... }）を提供します。 - 構造化データ:
schema-dts（WithContext<T>）を使用して型付けされたJSON-LDを注入し、<script type="application/ld+json">でラップします。<文字は\u003cとしてエスケープします。 - スキーマについては
references/seo-structured-data-guide.mdを参照してください。
4. 静的プリレンダリング（generateStaticParams）
- ページが
[locale]動的セグメント（または任意の動的セグメント）の下にネストされており、supported_languagesに複数のロケールが含まれている場合、すべてのサポート対象ロケールに対して{ locale }を返すgenerateStaticParams()をエクスポートします。
5. インスタントナビゲーションとGranular Suspense Push-Down
- Granular Loading States:
<Suspense>を特定の動的サブコンポーネントまでプッシュダウンし、静的/キャッシュされたセクション（ヘッダー、ヒーロー、キャッシュされた製品情報）が即座に Static Shell および App Shell に持ち上げられるようにします。 - オプトアウト: セグメントが本質的に動的であり、インスタントフィードバックが不要な場合は、
export const instant = falseを設定します。 - ストリーミングパターンについては
references/streaming-and-boundaries.mdを参照してください。
ワークフローステップ
-
ステップ 0: 実装計画の生成と承認ゲート
docs/project.jsonとlib/routes.ts内の対象ルート定義を読み取ります。- ページメタデータ、JSON-LDスキーマタイプ、翻訳名前空間、コンポーネントレイアウトを作成します。
- 新しい主要ページを作成する場合は、簡潔な実装計画をユーザーに提示します。
-
ステップ 1: 翻訳辞書への入力
- すべてのロケールファイル（
messages/en.json、messages/fa.jsonなど）に、専用のページ名前空間の下にページタイトル、メタ説明、ページ本文コピーを追加します。
- すべてのロケールファイル（
-
ステップ 2: コンパニオンスケルトンの作成（
loading.tsx）- ページがコンテンツをストリーミングまたはデータをフェッチする場合は、loading.tsx.template から
loading.tsxをデプロイします。
- ページがコンテンツをストリーミングまたはデータをフェッチする場合は、loading.tsx.template から
-
ステップ 3: ページコンポーネントの実装（
page.tsx）- page.tsx.template をデプロイしカスタマイズします:
- 非同期 props インターフェースを定義します（
params: Promise<{ locale: string, ... }>、searchParams）。 - 動的なタイトルと正規の代替を解決する
generateMetadata()をエクスポートします。 - ローカライズ/動的ルート用の
generateStaticParams()をエクスポートします。 <new_component_dir>/<page-name>/からセクションコンポーネントを構成するページRSCを実装します。<JsonLd>構造化データコンポーネントをレンダリングします。
- 非同期 props インターフェースを定義します（
- page.tsx.template をデプロイしカスタマイズします:
-
ステップ 4: 検証と健全性チェック
- ページ検証スクリプトを実行します:
- Windows (PowerShell):
pwsh .agents/skills/nextjs-page-dev/scripts/verify-page.ps1 -RoutePath <route_dir> - Linux / macOS (Bash):
bash .agents/skills/nextjs-page-dev/scripts/verify-page.sh <route_dir>
- Windows (PowerShell):
- TypeScriptエラーまたは欠落している辞書エラーがゼロであることを確認します。
- ページ検証スクリプトを実行します:
-
ステップ 5: 実装計画チェックリストの同期
- 完了したページインフラストラクチャ項目（
page.tsx、loading.tsx、error.tsx、generateMetadata、JSON-LD Schema、generateStaticParams()）をdocs/plan/05-pages-and-components.mdでチェックします。 - このページのすべてのコンポーネントサブチェックリストとページインフラストラクチャタスクが完了した場合、親ページ項目をチェックします（
- [x]）。
- 完了したページインフラストラクチャ項目（