Editing and preview
Contents
Next.XP lets Content Studio display the Next.js front end while editors work with draft content. The Next.XP app resolves the Next.js URL of the selected content, and Content Studio loads it directly from Next.js.
Preview handshake
Initialization
-
Allow the front end. When Content Studio loads, the Next.XP app uses XP’s CSP API to contribute the configured front-end origins to Content Studio’s Content Security Policy. This allows Content Studio to embed and connect to the Next.js front end. See Content Security Policy for the configuration.
-
Find the page URL. Content Studio asks the Next.XP app where to preview the selected content. Next.XP uses its configuration to locate the front-end baseUrl. The Next.XP app calls
/api/mappingson that Next.js server for rules that translate XP content paths into front-end paths, then appends the matching path to the configured URL. See App configuration. -
Open an authenticated preview. The Next.XP app adds an
xpquery parameter containing the XP project, the editor’s XP session ID, and a timestamp, encrypted with the shared secret. Content Studio opens this URL in its preview pane so Next.js can identify the project and editor’s session. -
Enable Draft Mode. Next.js redirects the browser to its
/api/previewroute. That route validates thexpparameter, sets the Draft Mode cookie, and redirects back to the content URL without the parameter.
For each preview request
Once setup is complete, page loads and refreshes use the existing draft cookie:
-
Request the page. The browser requests the content URL directly from Next.js, including its Draft Mode cookie.
-
Fetch and render draft content. The Next.js server uses the adapter to query Guillotine’s
draftbranch with the editor’s XP session. XP applies that user’s content permissions, and Next.js returns the rendered page to the browser. -
Fetch draft media. Images and attachments referenced by the page trigger separate browser requests to Next.js
/api/media. That route forwards the editor’s XP session to the XP media API and streams each response back without caching. See Draft media proxy.
Selecting another content item in Content Studio resolves a new preview URL through the Next.XP app, reusing the cached mapping rules. It does not repeat Draft Mode setup while the cookie remains valid. Navigation within the front end requests Next.js directly.
Implementation details
The starter’s next.config.js configures CORS headers that let Content Studio read front-end responses, such as the preview availability check. The allowed Content Studio origin comes from ENONIC_ADMIN, falling back to the origin of ENONIC_API.
Draft Mode setup is reused while the cookie remains valid for the current Next.js build. It runs again when preview is opened after the cookie expires, Draft Mode is disabled, or a new build is deployed. The CSP contribution applies whenever Content Studio itself loads; URL mapping rules are cached per project.
The starter handles the Draft Mode redirect in src/proxy.ts, which runs inside Next.js before page routing. See Routing for implementation details.
Leaving Draft Mode
Draft Mode persists while its browser cookie remains valid. Opening the front end in another tab can therefore continue to request draft content outside Content Studio.
The starter includes an exit button through the adapter’s DraftModeIndicator. It appears in Draft Mode when the page is opened directly, and is hidden inside Content Studio and other iframes. Clicking it disables Draft Mode and reloads the page without the xp parameter to show published content.
See Starter configuration to enable or remove the button in your front end and customize its label.
Authentication and permissions
Preview starts from an authenticated Enonic Content Studio session. The front end must supply the editor’s XP session when querying protected draft content. The adapter forwards a session supplied through its JSESSIONID_HEADER as a cookie on the Guillotine request.
When the session is forwarded, Guillotine evaluates the draft query as the same Enonic user who opened the preview. XP’s normal content permissions remain in effect: the rendered result contains only content that user is allowed to access.
The shared API token and the Next.js Draft Mode cookie have different purposes. The token authenticates calls between the Next.XP app and the protected front-end endpoints, while the Draft Mode cookie selects draft rendering. Neither replaces the editor’s XP identity or grants access to content by itself.
Browser requests for protected media need authentication separately from server-side Guillotine requests. The starter’s draft media proxy at /api/media forwards the editor’s XP session server-side. Published media uses the API or CDN directly. CORS headers do not transfer XP cookies between hosts or grant access to draft media.
Render modes
| Mode | Behavior |
|---|---|
|
|
Direct Next.js access. Uses published content and omits editing markup. |
|
|
Content Studio page editing. Uses draft content and adds component and region attributes. |
|
|
Content Studio preview contexts. Uses draft content in Next.js draft mode. |
|
|
Published XP context. |
Editing annotations
Content Studio recognizes rendered page structures through data-portal-component-type and data-portal-region attributes. Adapter adds these attributes through its base component and region views when the render mode is edit.
The supporting @enonic/react-components package also implements these annotations in its generic component wrapper and region renderers. Next.XP currently uses that package directly for rich-text rendering, while the adapter supplies the page-tree annotations in the standard integration.
Page editor integration
@enonic/page-editor 2 runs in the browser and connects the rendered Next.js page to Content Studio’s visual editor. The starter installs this package directly, while @enonic/react-components is installed through @enonic/nextjs-adapter. Both supporting libraries version independently of Next.XP.
The starter’s PageEditorScript client component initializes the library with init({editMode: renderMode === RENDER_MODE.EDIT}). In edit mode, the library communicates with Content Studio and requests component markup through editor events. In inline preview mode, it reports link clicks to Content Studio.
The adapter supplies component and region annotations in the rendered HTML; the page editor supplies the browser-side editing behavior. See the Page Editor reference for its API and communication protocol.
Component refresh
Content Studio can request one component instead of refreshing the complete page. The adapter restricts the page tree to that component, and MainView delegates to SingleComponent. The starter wraps the response in a marker that can be extracted safely.
PageEditorScript subscribes to the page editor’s component-load-request event, fetches the component response from Next.js, extracts the marked HTML, and passes it to renderComponent(). It also uses the library’s loading and error states while handling the request.
Security
The value of ENONIC_API_TOKEN env var in Next.js must match the secret configured for the selected front end in com.enonic.app.nextxp.cfg Enonic XP config file. Do not expose it through a NEXT_PUBLIC_ variable. Restrict the preview endpoints to HTTPS in production.
See Preview live view extension for the XP-side implementation, App configuration, and Starter configuration.