Next.js + Enonic XP Headless Integration (Next.XP)

Procedures

Step 1: Identify the workspace integration surface

1. Inspect the workspace for Next.js entry points (next.config.*, package.json with next dependency), Enonic XP app markers (build.gradle with com.enonic.xp), or existing Next.XP adapter references (@enonic/nextjs-adapter).
2. Execute node scripts/find-nextxp-targets.mjs . to inventory Next.js projects, .env files with ENONIC_* variables, component mapping files (_mappings.ts), and Guillotine query files when a Node runtime is available.
3. If a Node runtime is unavailable, inspect package.json, .env, and src/components/_mappings.ts manually to identify the integration surface.
4. If the workspace contains both an Enonic XP app and a Next.js frontend, confirm which side the task targets before proceeding.
5. If the workspace is not a Next.js + Enonic XP project, stop and explain that this skill does not apply.

Step 2: Configure the Enonic adapter

1. Read references/nextxp-reference.md before writing or modifying configuration.
2. Verify or create the .env (or .env.local for local development) file in the Next.js project root with the required variables:
   • ENONIC_API_TOKEN — shared secret for preview mode authentication.
   • ENONIC_APP_NAME — fully qualified Enonic application name (e.g., com.example.myproject).
   • ENONIC_MAPPINGS — locale-to-project/site mapping (e.g., en:intro/hmdb).
   • ENONIC_API — base URL for the Guillotine API endpoint (e.g., http://127.0.0.1:8080/site/).
3. Install the @enonic/nextjs-adapter package if not already present: npm install @enonic/nextjs-adapter.