contentful-nextjs

Contentful Next.js

このスキルを使用して、既存の Next.js アプリケーションに Contentful を統合します。

Contentful は、ヘッドレスの API ファーストな CMS（コンポーザブルコンテンツプラットフォーム）です。Next.js アプリは、配信 API とプレビュー API を通じて構造化コンテンツを取得できます。

対象範囲

• Next.js App Router と Pages Router。
• 公開済みコンテンツの配信（CDA）。
• Draft Mode によるプレビューコンテンツの配信（CPA）。
• 環境変数とクライアントのセットアップパターン。
• 安定したデプロイパスを実現する、環境エイリアス対応のセットアップ。

対象外

• パーソナライゼーション／最適化の実装。
• Studio Experiences SDK のセットアップ。
• コンテンツモデル戦略の全面的な設計。

Contentful MCP に関する注意

• セットアップ中に Contentful をエージェント経由で簡単に操作したい場合は、Contentful MCP サーバーのドキュメントを案内してください：https://www.contentful.com/developers/docs/tools/mcp-server/。
• このスキルは Next.js の実装に焦点を当てます。MCP に関する案内はセットアップを補完するものであり、アプリ側のクライアント接続設定に代わるものではありません。

プロジェクトの状態

echo "=== Contentful packages ===" && node -e "try{const p=require('./package.json');const d={...p.dependencies,...p.devDependencies};const c=Object.entries(d).filter(([k])=>k.includes('contentful'));console.log(c.length?c.map(([k,v])=>k+'@'+v).join('\n'):'(Contentful SDK not installed)')}catch{console.log('(no package.json)')}" 2>/dev/null
echo ""
echo "=== Contentful env vars ===" && grep -h CONTENTFUL .env.local .env 2>/dev/null | sed 's/=.*/=<set>/' || echo "(no Contentful env vars found in .env.local or .env)"
echo ""
echo "=== Router type ===" && ([ -d "app" ] && echo "App Router detected (app/ directory exists)" || ([ -d "pages" ] && echo "Pages Router detected (pages/ directory exists)" || echo "(could not detect router type)"))

ワークフロー

1. バージョン固有の案内が必要な場合は、https://github.com/vercel/next.js/releases で Next.js の最新安定版をオンラインで確認します。
2. Next.js プロジェクトの構成（App Router と Pages Router のどちらか）を確認します。
3. 必要な環境変数を設定します。不足している場合は、先に .env.local に追加するようユーザーに依頼し、各値の確認場所を説明します。
4. contentful SDK をインストールして初期化します。
5. 公開済みコンテンツの取得を実装します。
6. Draft Mode に対応した動作を追加します。
7. 最小限のテスト用ルート／ページとトラブルシューティングのチェックリストで検証します。

バージョン確認ポリシー

• 「最新の Next.js バージョン」に関する主張を、記憶だけに頼って行わないでください。
• アップグレード、互換性に関する回避策、またはバージョン固有の修正を推奨する前に、https://github.com/vercel/next.js/releases で確認してください。
• ユーザーが canary／RC の案内を明示的に求めない限り、最新のプレリリースではないタグをデフォルトとして扱います。

必須の環境変数

• CONTENTFUL_SPACE_ID - Contentful の URL（/spaces/<SPACE_ID>/...）または Space settings -> API keys で確認できます。
• CONTENTFUL_ACCESS_TOKEN - Space settings -> API keys にある CDA トークンです。
• CONTENTFUL_PREVIEW_ACCESS_TOKEN（プレビューのワークフロー用） - Space settings -> API keys にある CPA トークンです。

Contentful で API キーを作成すると、ここで必要な両方のトークンが取得できます：

• CDA トークン -> CONTENTFUL_ACCESS_TOKEN
• CPA トークン -> CONTENTFUL_PREVIEW_ACCESS_TOKEN

デフォルト

• ユーザーがルーターの種類を指定しない場合は、Next.js App Router の案内をデフォルトにします。
• 通常の配信には CDA ホストを使用します。
• Draft Mode が有効な場合は、preview.contentful.com とプレビュートークンを使用します。
• 実行時のクライアントをリリース環境の ID から切り離せるよう、クライアントの environment 値には環境エイリアス（例：master）を優先して使用します。
• Contentful クライアントの作成処理は、共有ユーティリティモジュールにまとめます。

参考資料

• Next.js のセットアップ
• プレビューと Draft Mode
• トラブルシューティング