Docs Developer Site
Developer Docs Next.XP next App Preview live view extension

Preview live view extension

Contents

The Next.XP app implements a custom Next.js preview in Content Studio through its "Next.js Preview" live view extension. The extension resolves each content item to a Next.js URL, and Content Studio loads that URL directly from the Next.js front end.

Public visitors access the Next.js deployment directly, allowing its normal hosting and caching behavior to remain in control.

Request flow

  1. Content Studio requests preview of content inside a site.

  2. The app selects the site’s named front-end configuration and shared secret.

  3. It encrypts the XP project with the secret into an xp parameter and fetches URL mapping rules from the front end’s /api/mappings.

  4. It resolves the content item to a Next.js URL using those rules and returns the URL, with the xp parameter, to Content Studio.

  5. Content Studio loads the URL in the preview pane. The front end validates the xp parameter through /api/preview, enables Next.js Draft Mode, and redirects to the requested content path.

  6. The adapter detects Draft Mode and fetches content from the project’s draft branch.

URL mappings

/api/mappings returns a JSON object with a mappings array of rules:

{
  "mappings": [
    {"sources": ["/.*"], "target": "/no/${siteRelativePath}"}
  ]
}
Field Meaning

sources

Conditions a content item must meet. A field:value entry compares a content field, for example type:portal:site; any other entry is a regular expression matched against the item’s site-relative path.

target

URL template relative to the front-end URL. ${siteRelativePath} is replaced by the item’s site-relative path; other ${field} placeholders are replaced by content field values.

matchAny

Optional. When true, one matching source is enough; otherwise all sources must match.

The starter returns a single catch-all rule and prefixes its target with the project’s locale, unless it is the default locale, using localizeMappings(). It answers 404 when the project in the blob is not listed in ENONIC_MAPPINGS; the live view extension then finds no mapping.

The app caches the rules per project, for up to 24 hours. A failed request is not cached.

Content Security Policy

Content Studio’s Content Security Policy must allow the Next.js origin to load the preview. The app uses XP 8.1’s CSP API through an extension response processor to add the origin of every URL in com.enonic.app.nextxp.cfg to the frame-src, connect-src, and style-src directives. These contributions extend the existing policy; no manual contentSecurityPolicy.header configuration for Next.XP is needed.

When no URL is configured, the default http://localhost:3000 origin is added only when XP runs in dev mode.

Front-end selection

The configurations XP service backs the site’s Configuration name CustomSelector. It returns the names and URLs defined in com.enonic.app.nextxp.cfg, allowing each site to select a front end. Shared secrets are never included in the selector response.

See App configuration for defining front-end targets and tokens.

Front-end endpoints

The preview flow uses two protected route handlers implemented by the Next.js front end. The starter provides their canonical implementations.

Endpoint Purpose

/api/preview

Validates the xp parameter, establishes Next.js Draft Mode, and redirects to the requested route.

/api/mappings

Returns the rules the app uses to resolve content items to Next.js URLs.

Component refresh

Content Studio can request one component without refreshing the complete page. The request goes directly to Next.js; the app is not involved. The adapter restricts the page tree to the requested component, and MainView delegates rendering to SingleComponent.

Security

Both front-end endpoints must validate the xp parameter encrypted with the configured shared secret. Use HTTPS outside a trusted local network, keep the token out of public environment variables, and ensure both the XP server and the editor’s browser can reach the configured front-end URL.

See Editing and preview for the complete editor-facing flow and render modes.

Contents

Contents