enonic-nextxp-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Next.js + Enonic XP 无头集成（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

Read
```
references/nextxp-reference.md
```
for the deployment checklist.
Deploy the Enonic app to Enonic Cloud using
```
enonic cloud app install
```
.
Create an ingress in Enonic Cloud to expose the Guillotine API (target path
```
/site
```
, public path
```
/api
```
).
Deploy the Next.js app to Vercel or another hosting platform.

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.

步骤1：确定工作区集成范围

检查工作区是否存在Next.js入口文件（
```
next.config.*
```
、含
```
next
```
依赖的
```
package.json
```
）、Enonic XP应用标记（含
```
com.enonic.xp
```
的
```
build.gradle
```
），或是已有的Next.XP适配器引用（
```
@enonic/nextjs-adapter
```
）。
当存在Node运行环境时，执行
```
node scripts/find-nextxp-targets.mjs .
```
来清点Next.js项目、含
```
ENONIC_*
```
变量的
```
.env
```
文件、组件映射文件（
```
_mappings.ts
```
）以及Guillotine查询文件。
若无Node运行环境，手动检查
```
package.json
```
、
```
.env
```
和
```
src/components/_mappings.ts
```
来确认集成范围。
如果工作区同时包含Enonic XP应用和Next.js前端，先确认当前任务的目标端再继续操作。
如果工作区不是Next.js + Enonic XP项目，停止操作并说明本指南不适用该场景。

步骤2：配置Enonic适配器

编写或修改配置前请先阅读
```
references/nextxp-reference.md
```
。
验证或在Next.js项目根目录创建
```
.env
```
（本地开发则用
```
.env.local
```
）文件，填入必填变量：
- ```
ENONIC_API_TOKEN
```
  — 预览模式身份校验的共享密钥。
- ```
ENONIC_APP_NAME
```
  — 全限定的Enonic应用名称（例如
```
com.example.myproject
```
  ）。
- ```
ENONIC_MAPPINGS
```
  — locale到项目/站点的映射（例如
```
en:intro/hmdb
```
  ）。
- ```
ENONIC_API
```
  — Guillotine API端点的基础URL（例如
```
http://127.0.0.1:8080/site
```
  ）。
若尚未安装
```
@enonic/nextjs-adapter
```
包则进行安装，使用与Next.js版本匹配的版本：Next.js 16+执行
```
npm install @enonic/nextjs-adapter@4
```
，Next.js 14.x执行
```
npm install @enonic/nextjs-adapter@3
```
。版本要求可参考
```
references/compatibility.md
```
。
验证Next.js项目是基于
```
nextxp-template
```
搭建的，或是符合预期的文件结构：包含
```
src/components/_mappings.ts
```
、
```
src/app/[locale]/[[...contentPath]]/page.tsx
```
，以及
```
src/app/api/
```
下的API路由。
阅读
```
references/compatibility.md
```
确认
```
@enonic/nextjs-adapter
```
、Next.js和Enonic XP之间的版本适配要求。

步骤3：将内容类型映射到React组件

阅读
```
references/nextxp-reference.md
```
了解组件注册API和映射规则。
阅读
```
references/examples.md
```
查看完整的内容类型映射示例，包括查询、视图和处理器。
对于每个需要自定义渲染的Enonic内容类型： a. 在
```
src/components/queries/
```
下创建Guillotine GraphQL查询函数，通过类型自省（
```
... on AppName_ContentTypeName
```
）拉取该内容类型的专属字段。 b. 在
```
src/components/views/
```
下创建React视图组件，接收
```
FetchContentResult
```
属性并渲染拉取到的数据。 c. 在
```
src/components/_mappings.ts
```
中通过
```
ComponentRegistry.addContentType()
```
注册上述查询和组件。
对于页面组件（页面、部件、布局）： a. 在Enonic应用的
```
src/main/resources/site/pages/
```
、
```
parts/
```
或
```
layouts/
```
目录下定义组件XML。 b. 在
```
src/components/pages/
```
、
```
parts/
```
或
```
layouts/
```
目录下创建对应的React组件。 c. 通过
```
ComponentRegistry.addPage()
```
、
```
ComponentRegistry.addPart()
```
或
```
ComponentRegistry.addLayout()
```
进行注册。
使用
```
@enonic/nextjs-adapter
```
导出的
```
APP_NAME
```
和
```
APP_NAME_UNDERSCORED
```
保持内容类型引用的动态性。

步骤4：配置Guillotine数据拉取

阅读
```
references/nextxp-reference.md
```
了解Guillotine查询结构和变量传递规则。
编写GraphQL查询时，使用
```
$path:ID!
```
作为内容检索的主要变量，格式为
```
guillotine { get(key:$path) { ... } }
```
。
使用类型自省访问内容类型专属字段：
```
... on AppName_ContentTypeName { data { ... } }
```
。
对于部件和可配置组件，导出包含
```
query(path, context, config)
```
和
```
variables(path, context, config)
```
函数的查询对象。
可使用处理器（可选异步函数）在将查询结果传递给视图前进行后处理。
所有页面组件共享的数据可通过
```
ComponentRegistry.setCommonQuery()
```
配置。若不需要通用查询可移除，以优化性能。
使用适配器提供的
```
getUrl()
```
和
```
getAsset()
```
辅助函数处理URL，确保在独立运行和Content Studio预览模式下都能正常工作。

步骤5：启用Content Studio预览模式

阅读
```
references/nextxp-reference.md
```
了解完整的预览架构细节。

在Enonic XP中安装

Next.XP

应用：

XP菜单 → 应用 → 安装 → 搜索"Next.XP"

。

在Content Studio的站点编辑视图中，通过「应用」下拉框将Next.XP应用添加到目标站点。
验证默认预览配置：URL为
```
http://127.0.0.1:3000
```
，密钥与
```
ENONIC_API_TOKEN
```
一致。
生产环境需要通过应用配置为Next.XP应用设置已部署的Next.js URL和共享密钥：
```
nextjs.default.url = <Next.js应用URL>
nextjs.default.secret = <共享密钥>
```
预览模式会自动将Guillotine API切换到
```
draft
```
分支，而公开的Next.js前端使用
```
master
```
（已发布）分支。
所有组件链接都使用
```
getUrl()
```
生成，确保URL在Content Studio的预览、内嵌和编辑模式下都能正确解析。
如果预览显示空白页，可阅读
```
references/troubleshooting.md
```
查看诊断步骤。

步骤6：部署到生产环境

阅读
```
references/nextxp-reference.md
```
查看部署检查清单。
使用
```
enonic cloud app install
```
命令将Enonic应用部署到Enonic Cloud。
在Enonic Cloud中创建入口，对外暴露Guillotine API（目标路径
```
/site
```
，公开路径
```
/api
```
）。
将Next.js应用部署到Vercel或其他托管平台。

设置生产环境变量：

ENONIC_API

、

ENONIC_APP_NAME

、

ENONIC_API_TOKEN

、

ENONIC_MAPPINGS

。

配置Enonic Cloud中的Next.XP应用，使其指向生产环境的Next.js URL。
在Content Studio中发布内容，使其在正式前端站点可见。

步骤7：验证集成效果

执行
```
node scripts/find-nextxp-targets.mjs .
```
确认适配器、映射和环境变量配置仍可正常解析。
访问
```
http://localhost:3000
```
验证Next.js独立渲染可正常展示已发布内容。
验证Content Studio预览可正常渲染草稿和已发布内容。
访问内容URL确认自定义视图正常渲染，校验内容类型映射是否生效。
执行工作区构建命令（
```
npm run build
```
）排查TypeScript或构建错误。

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

如果Content Studio预览显示空白页，阅读
```
references/troubleshooting.md
```
排查预览代理、令牌不匹配、CORS相关问题。
如果Guillotine查询返回空数据或不符合预期，验证内容类型名称是否匹配自省规则，并在GraphQL Playground（地址为
```
http://localhost:8080/site/<项目名>
```
）中测试查询。
如果
```
@enonic/nextjs-adapter
```
导入失败，查看
```
references/compatibility.md
```
的版本要求，确认包已正确安装。
如果内容在预览中正常渲染但公开站点不显示，验证内容已发布（已从
```
draft
```
分支移动到
```
master
```
分支）。
如果组件映射未生效，验证
```
_mappings.ts
```
中的注册项使用了正确的全限定内容类型/组件名称，且搭配了
```
APP_NAME
```
变量。