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

Procedures

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.

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. Use the version matching the Next.js version:

   npm install @enonic/nextjs-adapter@4

   for Next.js 16+ or

   npm install @enonic/nextjs-adapter@3

   for Next.js 14.x. See

   references/compatibility.md

   for version requirements.
4. 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/

   .
5. Read

   references/compatibility.md

   to confirm version requirements between

   @enonic/nextjs-adapter

   , Next.js, and Enonic XP.

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. Create a React view component in

   src/components/views/

   that accepts

   FetchContentResult

   props and renders the fetched data. c. 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/

   . c. Register using

   ComponentRegistry.addPage()

   ,

   ComponentRegistry.addPart()

   , or

   ComponentRegistry.addLayout()

   .
5. Use

   APP_NAME

   and

   APP_NAME_UNDERSCORED

   imports from

   @enonic/nextjs-adapter

   to keep content type references dynamic.

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 parts and configurable components, export a query object with

   query(path, context, config)

   and

   variables(path, context, config)

   functions.
5. Use processors (optional async functions) to post-process query results before passing to the view.
6. Use

   ComponentRegistry.setCommonQuery()

   for data shared across all page components. Remove the common query if not needed to optimize performance.
7. Use

   getUrl()

   and

   getAsset()

   helper functions from the adapter for URL handling that works in both standalone and Content Studio preview modes.

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.

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.

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. 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 matches the introspection pattern and test the query in GraphQL Playground at

  http://localhost:8080/site/<project>

  .
• If

  @enonic/nextjs-adapter

  imports fail, check

  references/compatibility.md

  for version requirements and confirm the package is installed.
• If content renders in preview but not on the public site, verify the content is published (moved from

  draft

  to

  master

  branch).
• If component mappings are not applied, verify registrations in

  _mappings.ts

  use the correct fully-qualified content type or component name with

  APP_NAME

  .