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

Procedures

Step 1: Identify the workspace integration surface

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
```
).
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.
If a Node runtime is unavailable, inspect
```
package.json
```
,
```
.env
```
, and
```
src/components/_mappings.ts
```
manually to identify the integration surface.
If the workspace contains both an Enonic XP app and a Next.js frontend, confirm which side the task targets before proceeding.
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

Read
```
references/nextxp-reference.md
```
before writing or modifying configuration.
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
```
  ).
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.
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/
```
.
Read
```
references/compatibility.md
```
to confirm version requirements between
```
@enonic/nextjs-adapter
```
, Next.js, and Enonic XP.

Step 3: Map content types to React components

Read
```
references/nextxp-reference.md
```
for the component registry API and mapping patterns.
Read
```
references/examples.md
```
for complete content type mapping examples including queries, views, and processors.
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()
```
.
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()
```
.
Use
```
APP_NAME
```
and
```
APP_NAME_UNDERSCORED
```
imports from
```
@enonic/nextjs-adapter
```
to keep content type references dynamic.

Step 4: Configure Guillotine data fetching

Read
```
references/nextxp-reference.md
```
for the Guillotine query structure and variable passing.
Write GraphQL queries that use
```
$path:ID!
```
as the primary variable for content retrieval via
```
guillotine { get(key:$path) { ... } }
```
.
Use type introspection to access content-type-specific fields:
```
... on AppName_ContentTypeName { data { ... } }
```
.
For parts and configurable components, export a query object with
```
query(path, context, config)
```
and
```
variables(path, context, config)
```
functions.
Use processors (optional async functions) to post-process query results before passing to the view.
Use
```
ComponentRegistry.setCommonQuery()
```
for data shared across all page components. Remove the common query if not needed to optimize performance.
Use
```
getUrl()
```
and
```
getAsset()
```
helper functions from the adapter for URL handling that works in both standalone and Content Studio preview modes.

Step 5: Enable Content Studio preview mode

Read
```
references/nextxp-reference.md
```
for full preview architecture details.

Install the

Next.XP

app in Enonic XP:

XP Menu → Applications → Install → search "Next.XP"

Add the Next.XP app to the target site in Content Studio via the "Applications" combobox on the site edit view.
Verify default preview configuration: URL
```
http://127.0.0.1:3000
```
and secret matching
```
ENONIC_API_TOKEN
```
.
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>
```
Preview mode automatically switches the Guillotine API to the
```
draft
```
branch, while the public Next.js frontend uses the
```
master
```
(published) branch.
Use
```
getUrl()
```
in all component links to ensure URLs resolve correctly across preview, inline, and edit modes in Content Studio.
If preview shows a blank page, read
```
references/troubleshooting.md
```
for diagnostic steps.

Step 6: Deploy to production

Set production environment variables:

ENONIC_API

ENONIC_APP_NAME

ENONIC_API_TOKEN

ENONIC_MAPPINGS

Configure the Next.XP app in Enonic Cloud to point to the production Next.js URL.
Publish content in Content Studio to make it visible on the live frontend.

Step 7: Validate the integration

Execute
```
node scripts/find-nextxp-targets.mjs .
```
to confirm the adapter, mappings, and env configuration still resolve correctly.
Verify that standalone Next.js rendering works at
```
http://localhost:3000
```
with published content.
Verify Content Studio preview renders correctly for both draft and published content.
Test content type mappings by visiting content URLs and confirming custom views render.
Run the workspace build (
```
npm run build
```
) to catch TypeScript or build errors.

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
```
.