enonic-nextxp-integration

What this skill does

# 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`.
4. Import `@enonic/nextjs-adapter/baseMappings` at the top of `src/components/_mappings.ts` to register built-in component renderers.
5. Verify the Next.js project was scaffolded from the `nextxp-template` or contains the expected file structure: `src/components/_mappings.ts`, `src/app/[locale]/[[...contentPath]]/page.tsx`, and API routes under `src/app/api/`.
6. Read `references/compatibility.md` to confirm version requirements between `@enonic/nextjs-adapter` (v4.x), Next.js (16+), React (19), and Enonic XP.

**Step 3: Map content types to React components**
1. Read `references/nextxp-reference.md` for the component registry API and mapping patterns.
2. Read `references/examples.md` for complete content type mapping examples including queries, views, and processors.
3. For each Enonic content type that needs a custom rendering:
   a. Create a Guillotine GraphQL query function in `src/components/queries/` that fetches the fields specific to that content type using type introspection (`... on AppName_ContentTypeName`).
   b. For content types with HTML area (rich text) fields, use `richTextQuery(fieldName)` from `@enonic/nextjs-adapter` to generate the query fragment. See `references/nextxp-reference.md` for the rich text rendering section.
   c. Create a React view component in `src/components/views/` that accepts `FetchContentResult` props and renders the fetched data. Use `RichTextView` from `@enonic/nextjs-adapter/views/RichTextView` for HTML area fields.
   d. Register both in `src/components/_mappings.ts` using `ComponentRegistry.addContentType()`.
4. For page components (pages, parts, layouts):
   a. Define the component XML in the Enonic app under `src/main/resources/site/pages/`, `parts/`, or `layouts/`.
   b. Create a corresponding React component in `src/components/pages/`, `parts/`, or `layouts/`. Use `LayoutProps` for layouts and the named `RegionView` export for individual region rendering.
   c. Register using `ComponentRegistry.addPage()`, `ComponentRegistry.addPart()`, or `ComponentRegistry.addLayout()`.
5. For layouts, use `LayoutProps` type and `RegionView` (singular, named export) for individual regions instead of `RegionsView`.
6. Use `APP_NAME` and `APP_NAME_UNDERSCORED` imports from `@enonic/nextjs-adapter` to keep content type references dynamic.

**Step 4: Configure Guillotine data fetching**
1. Read `references/nextxp-reference.md` for the Guillotine query structure and variable passing.
2. Write GraphQL queries that use `$path:ID!` as the primary variable for content retrieval via `guillotine { get(key:$path) { ... } }`.
3. Use type introspection to access content-type-specific fields: `... on AppName_ContentTypeName { data { ... } }`.
4. For rich text fields (HtmlArea), use `richTextQuery(fieldName)` from the adapter instead of querying the field directly. Render with `RichTextView` from `@enonic/nextjs-adapter/views/RichTextView`.
5. For parts and configurable components, export a query object with `query(path, context, config)` and `variables(path, context, config)` functions.
6. Use processors (optional async functions) to post-process query results before passing to the view.
7. Use `ComponentRegistry.setCommonQuery()` for data shared across all page components. Remove the common query if not needed to optimize performance.
8. Use `getUrl()` and `getAsset()` helper functions from the adapter for URL handling that works in both standalone and Content Studio preview modes.
9. For macros in rich text, register them with `ComponentRegistry.addMacro()` before other components that use `RichTextView`. See `references/nextxp-reference.md` for the macro registration API.

**Step 5: Enable Content Studio preview mode**
1. Read `references/nextxp-reference.md` for full preview architecture details.
2. Install the `Next.XP` app in Enonic XP: `XP Menu → Applications → Install → search "Next.XP"`.
3. Add the Next.XP app to the target site in Content Studio via the "Applications" combobox on the site edit view.
4. Verify default preview configuration: URL `http://127.0.0.1:3000` and secret matching `ENONIC_API_TOKEN`.
5. For production, configure the Next.XP app with the deployed Next.js URL and shared secret via app config:
   ```
   nextjs.default.url = <Next.js app URL>
   nextjs.default.secret = <shared secret>
   ```
6. Preview mode automatically switches the Guillotine API to the `draft` branch, while the public Next.js frontend uses the `master` (published) branch.
7. Use `getUrl()` in all component links to ensure URLs resolve correctly across preview, inline, and edit modes in Content Studio.
8. If preview shows a blank page, read `references/troubleshooting.md` for diagnostic steps.

**Step 6: Deploy to production**
1. Read `references/nextxp-reference.md` for the deployment checklist.
2. Deploy the Enonic app to Enonic Cloud using `enonic cloud app install`.
3. Create an ingress in Enonic Cloud to expose the Guillotine API (target path `/site`, public path `/api`).
4. Deploy the Next.js app to Vercel or another hosting platform.
5. Set production environment variables: `ENONIC_API`, `ENONIC_APP_NAME`, `ENONIC_API_TOKEN`, `ENONIC_MAPPINGS`.
6. Configure the Next.XP app in Enonic Cloud to point to the production Next.js URL.
7. Publish content in Content Studio to make it visible on the live frontend.

**Step 7: Validate the integration**
1. Execute `node scripts/find-nextxp-targets.mjs .` to confirm the adapter, mappings, and env configuration still resolve correctly.
2. Verify that standalone Next.js rendering works at `http://localhost:3000` with published content.
3. Verify Content Studio preview renders correctly for both draft and published content.
4. Test content type mappings by visiting content URLs and confirming custom views render.
5. Use `validateData()` from `@enonic/nextjs-adapter` in the page handler to catch invalid content responses. See `references/nextxp-reference.md` for the SSG page handler pattern.
6. Run the workspace build (`npm run build`) to catch TypeScript or build errors.

## Error Handling
* If Content Studio preview shows a blank page, read `references/troubleshooting.md` for preview proxy diagnostics, token mismatch detection, and CORS issues.
* If Guillotine queries return empty or unexpected data, verify the content type name