enonic-nextxp-integration

Next.js + Enonic XP ヘッドレス統合（Next.XP）

手順

ステップ 1：ワークスペースの統合対象を特定する

1. ワークスペースを調べて、Next.js のエントリーポイント（next.config.*、next 依存関係を含む package.json）、Enonic XP アプリのマーカー（com.enonic.xp を含む build.gradle）、または既存の Next.XP アダプター参照（@enonic/nextjs-adapter）を確認します。
2. Node ランタイムが利用できる場合は、node scripts/find-nextxp-targets.mjs . を実行し、Next.js プロジェクト、ENONIC_* 変数を含む .env ファイル、コンポーネントマッピングファイル（_mappings.ts）、Guillotine クエリファイルを一覧表示します。
3. Node ランタイムが利用できない場合は、package.json、.env、src/components/_mappings.ts を手動で調べ、統合対象を特定します。
4. ワークスペースに Enonic XP アプリと Next.js フロントエンドの両方が含まれている場合は、先に進む前にタスクの対象がどちらかを確認します。
5. ワークスペースが Next.js + Enonic XP プロジェクトではない場合は、作業を中止し、このスキルが適用されないことを説明します。

ステップ 2：Enonic アダプターを設定する

1. 設定を記述または変更する前に、references/nextxp-reference.md を読みます。
2. Next.js プロジェクトのルートに、必要な変数を含む .env（ローカル開発の場合は .env.local）ファイルがあることを確認するか、作成します。
   • ENONIC_API_TOKEN — プレビューモード認証に使用する共有シークレットです。
   • ENONIC_APP_NAME — 完全修飾された Enonic アプリケーション名です（例：com.example.myproject）。
   • ENONIC_MAPPINGS — ロケールとプロジェクト／サイトのマッピングです（例：en:intro/hmdb）。
   • ENONIC_API — Guillotine API エンドポイントのベース URL です（例：http://127.0.0.1:8080/site/）。
3. @enonic/nextjs-adapter パッケージがまだインストールされていない場合は、インストールします：npm install @enonic/nextjs-adapter。
4. 組み込みコンポーネントレンダラーを登録するため、src/components/_mappings.ts の先頭で @enonic/nextjs-adapter/baseMappings をインポートします。
5. Next.js プロジェクトが nextxp-template からスキャフォールディングされていること、または想定されるファイル構造（src/components/_mappings.ts、src/app/[locale]/[[...contentPath]]/page.tsx、src/app/api/ 以下の API ルート）を含んでいることを確認します。
6. @enonic/nextjs-adapter（v4.x）、Next.js（16+）、React（19）、Enonic XP 間のバージョン要件を確認するため、references/compatibility.md を読みます。 ステップ 3：コンテンツタイプを React コンポーネントに対応付ける
7. コンポーネントレジストリ API とマッピングパターンについて、references/nextxp-reference.md を読みます。
8. クエリ、ビュー、プロセッサを含むコンテンツタイプの完全なマッピング例について、references/examples.md を読みます。
9. カスタムレンダリングが必要な Enonic コンテンツタイプごとに、次の手順を実行します。 a. src/components/queries/ に Guillotine GraphQL クエリ関数を作成し、型イントロスペクション（... on AppName_ContentTypeName）を使って、そのコンテンツタイプ固有のフィールドを取得します。 b. HTML area（リッチテキスト）フィールドがあるコンテンツタイプでは、@enonic/nextjs-adapter の richTextQuery(fieldName) を使ってクエリフラグメントを生成します。リッチテキストのレンダリングについては、references/nextxp-reference.md を参照してください。 c. src/components/views/ に React ビューコンポーネントを作成し、FetchContentResult の props を受け取り、取得したデータをレンダリングします。HTML area フィールドには、@enonic/nextjs-adapter/views/RichTextView の RichTextView を使います。 d. ComponentRegistry.addContentType() を使って、両方を src/components/_mappings.ts に登録します。
10. ページコンポーネント（ページ、パーツ、レイアウト）については、次の手順を実行します。 a. Enonic アプリの src/main/resources/site/pages/、parts/、または layouts/ にコンポーネント XML を定義します。 b. 対応する React コンポーネントを src/components/pages/、parts/、または layouts/ に作成します。レイアウトには LayoutProps を使い、各リージョンのレンダリングには名前付きエクスポートの RegionView を使います。 c. ComponentRegistry.addPage()、ComponentRegistry.addPart()、または ComponentRegistry.addLayout() を使って登録します。
11. レイアウトでは LayoutProps 型を使い、各リージョンのレンダリングには RegionsView ではなく RegionView（単数形、名前付きエクスポート）を使います。
12. コンテンツタイプの参照を動的に保つには、@enonic/nextjs-adapter から APP_NAME と APP_NAME_UNDERSCORED をインポートします。

ステップ 4：Guillotine のデータ取得を設定する

1. Guillotine のクエリ構造と変数の受け渡しについて、references/nextxp-reference.md を読みます。
2. guillotine { get(key:$path) { ... } } を通じてコンテンツを取得するための主な変数として、$path:ID! を使う GraphQL クエリを記述します。
3. 型イントロスペクションを使って、コンテンツタイプ固有のフィールドにアクセスします：... on AppName_ContentTypeName { data { ... } }。
4. リッチテキストフィールド（HtmlArea）には、フィールドを直接クエリする代わりに、アダプターの richTextQuery(fieldName) を使います。@enonic/nextjs-adapter/views/RichTextView の RichTextView でレンダリングします。
5. パーツと設定可能なコンポーネントについては、query(path, context, config) 関数と variables(path, context, config) 関数を含むクエリオブジェクトをエクスポートします。
6. ビューワーに渡す前にクエリ結果を後処理するには、プロセッサ（非同期関数、任意）を使います。
7. すべてのページコンポーネントで共有するデータには、ComponentRegistry.setCommonQuery() を使います。パフォーマンスを最適化するために不要な場合は、共通クエリを削除します。
8. スタンドアロンモードと Content Studio プレビューの両方で機能する URL 処理には、アダプターの getUrl() と getAsset() ヘルパー関数を使います。
9. リッチテキスト内のマクロは、RichTextView を使う他のコンポーネントより前に、ComponentRegistry.addMacro() で登録します。マクロ登録 API については、references/nextxp-reference.md を参照してください。 Step 5: Content Studio のプレビュー モードを有効にする
10. プレビュー アーキテクチャの詳細については、references/nextxp-reference.md をお読みください。
11. Enonic XP に Next.XP アプリをインストールします：XP Menu → Applications → Install → search "Next.XP"。
12. サイト編集画面の「Applications」コンボボックスを使用して、Content Studio で対象サイトに Next.XP アプリを追加します。
13. デフォルトのプレビュー設定を確認します：URL は http://127.0.0.1:3000、シークレットは ENONIC_API_TOKEN と一致している必要があります。
14. 本番環境では、アプリ設定で Next.XP アプリにデプロイ済みの Next.js URL と共有シークレットを設定します：

    nextjs.default.url = <Next.js app URL>
    nextjs.default.secret = <shared secret>
    

15. プレビュー モードでは Guillotine API が自動的に draft ブランチに切り替わり、公開中の Next.js フロントエンドでは master（公開済み）ブランチが使用されます。
16. Content Studio のプレビュー、インライン、編集の各モードで URL が正しく解決されるよう、すべてのコンポーネントのリンクで getUrl() を使用します。
17. プレビューに空白のページが表示される場合は、診断手順について references/troubleshooting.md をお読みください。

Step 6: 本番環境にデプロイする

1. デプロイのチェックリストについては、references/nextxp-reference.md をお読みください。
2. enonic cloud app install を使用して Enonic Cloud に Enonic アプリをデプロイします。
3. Enonic Cloud で Guillotine API を公開するための ingress を作成します（target path は /site、public path は /api）。
4. Next.js アプリを Vercel または別のホスティングプラットフォームにデプロイします。
5. 本番環境の環境変数を設定します：ENONIC_API、ENONIC_APP_NAME、ENONIC_API_TOKEN、ENONIC_MAPPINGS。
6. Enonic Cloud の Next.XP アプリを、本番環境の Next.js URL を参照するように設定します。
7. Content Studio でコンテンツを公開し、ライブ フロントエンドに表示されるようにします。

Step 7: 統合を検証する

1. node scripts/find-nextxp-targets.mjs . を実行し、アダプター、マッピング、環境設定が引き続き正しく解決されることを確認します。
2. 公開済みコンテンツを使用して、http://localhost:3000 でスタンドアロンの Next.js レンダリングが動作することを確認します。
3. Content Studio のプレビューで、下書きコンテンツと公開済みコンテンツの両方が正しくレンダリングされることを確認します。
4. コンテンツの URL にアクセスし、カスタムビューがレンダリングされることを確認して、コンテンツタイプのマッピングをテストします。
5. ページハンドラーで @enonic/nextjs-adapter の validateData() を使用し、無効なコンテンツレスポンスを検出します。SSG ページハンドラーのパターンについては、references/nextxp-reference.md を参照してください。
6. ワークスペースのビルド（npm run build）を実行して、TypeScript またはビルドのエラーを検出します。

エラー処理

• Content Studio のプレビューに空白のページが表示される場合は、プレビュー プロキシの診断、トークン不一致の検出、CORS の問題について references/troubleshooting.md をお読みください。
• Guillotine クエリが空または予期しないデータを返す場合は、コンテンツタイプ名がイントロスペクションのパターンと一致していることを確認し、http://localhost:8080/site/<project> の GraphQL Playground でクエリをテストしてください。
• @enonic/nextjs-adapter のインポートに失敗する場合は、バージョン要件について references/compatibility.md を確認し、パッケージがインストールされていることを確認してください。
• プレビューではコンテンツがレンダリングされるのに公開サイトでは表示されない場合は、コンテンツが公開済みであること（draft ブランチから master ブランチに移動していること）を確認してください。
• コンポーネントのマッピングが適用されない場合は、_mappings.ts の登録で APP_NAME とともに正しい完全修飾コンテンツタイプ名またはコンポーネント名を使用していることを確認してください。