Upgrading from v5

Contents

Prepare the XP environment for Next.XP 6, then create a front end from the v6 starter and move your application code into it. The starter supplies the new preview and revalidation routes, locale proxy, page editor integration, and Next.js configuration. Keep that integration and adapt your custom code as described below.

This approach reuses your XP applications, projects, and content. Keep the existing front end available for comparison while migrating.

Prepare the XP environment

Upgrade the XP environment to Enonic XP 8.1 or later, Content Studio 6.1 or later, Guillotine 9, and Next.XP app 6.

Update the following XP configuration files in <xp-home>/config/:

com.enonic.app.nextxp.cfg

The property format is unchanged. Set nextjs.<name>.url to the new front-end URL. Generate a new shared secret for nextjs.<name>.secret and use the same value for ENONIC_API_TOKEN in the new front end; do not reuse the v5 secret. For production deployments, explicitly configure the front-end URL. See App configuration.

Site setup is unchanged: add the Next.XP app to each rendered XP site and select its front-end configuration.

com.enonic.app.contentstudio.cfg

Remove manual Next.XP-specific additions to contentSecurityPolicy.header, retaining any unrelated custom policy. The Next.XP app now adds its configured front-end origins to Content Studio’s Content Security Policy through XP’s CSP API.

Create the v6 front end

Use Node.js 24.15.0 or later and npm 10.9.2 or later for the new front end. The starter supplies the compatible Next.js, React, adapter, and page editor dependencies; see Front-end dependencies.

Create a separate front-end project from starter-nextjs, following the starter usage instructions.

Keep the starter’s proxy, integration routes, utilities, and next.config.js as the baseline. These already implement the encrypted preview handshake, Draft Mode, URL mappings, revalidation, and CORS configuration.

Configure the Next.js environment file:

.env (Next.js)

Carry over ENONIC_APP_NAME and ENONIC_MAPPINGS, keeping the same default locale unless you intend to change your public URLs. Set ENONIC_API_TOKEN to the new secret configured in com.enonic.app.nextxp.cfg, storing it in .env.local or deployment secrets.

Update ENONIC_API to the XP API root:

# v5
ENONIC_API=http://localhost:8080/site

# v6
ENONIC_API=http://localhost:8080/api

Remove all old NEXT_PUBLIC_ variables from environment files and deployment settings. Keep the Next.XP configuration server-side, and update custom client components to receive only the required non-secret data or resolved URLs from the server. Rebuild and redeploy the front end so its browser bundles no longer contain the old values.

Review ENONIC_MEDIA_CDN and ENONIC_ADMIN against the configuration reference if your deployment needs these overrides.

See Starter environment for an example.

Move your application code

Move the following into the new project, adapting queries and adapter calls as described in the next section:

  • Custom React views for content types, pages, layouts, parts, and macros.

  • Component registrations and shared queries. Merge registrations into src/components/_mappings.ts, preserving the starter’s base mappings import.

  • Styles, public assets, and locale dictionaries under src/phrases/.

  • Application-specific routes, metadata, and business logic.

Add your application’s dependencies to the new package.json, preserving the starter’s integration dependencies. Register explicit mappings for every content type and page component used by the site; the development fallback is not a production view.

Merge custom layout and routing behavior into the starter’s structure. Preserve its page editor initialization, single-component rendering wrapper, and Draft Mode indicator. These support visual editing, component refreshes, and returning to the published site. See Starter and Editing and preview.

Reapply custom authentication, redirects, bundler settings, and deployment configuration where needed. When adding public asset folders or custom routes, check that the locale proxy does not treat them as content paths.

The old /api/renderable route is no longer used and should not be carried over.

Adapt your queries and views

Update custom GraphQL queries

This is a required change for custom queries you bring into the new project. The queries supplied by the v6 starter are already updated.

Guillotine 9 receives the project, branch, and site context as query arguments instead of deriving them from the endpoint URL. In custom queries that call guillotine(), pass scopeKey, project, and branch. If your queries use the earlier siteKey name, replace the siteKey argument with scopeKey and rename $siteKey to $scopeKey in declarations and references. Update any matching keys in custom variables objects too.

query($path: ID!, $scopeKey: String, $project: String, $branch: String) {
  guillotine(scopeKey: $scopeKey, project: $project, branch: $branch) {
    get(key: $path) {
      displayName
    }
  }
}

For queries registered with the adapter, it supplies the values of path, scopeKey, project, and branch; you do not need to add code to determine them. If your code calls Guillotine directly, supply those values in the request variables yourself.

Update custom query callbacks

If you have custom query or variables callbacks, update their first argument from a content-path string to a GlobalVariables object. Read the path from vars.path. A variables callback must return the supplied variables along with any custom ones:

import type {GlobalVariables} from '@enonic/nextjs-adapter';

export function commonVariables(vars: GlobalVariables) {
    return {...vars, count: 10};
}

Declare and use any custom variables in the corresponding query. The starter’s callbacks already use this signature. See Components and views for query registration and Server API for direct requests.

Media and page URLs

The imageUrl, mediaUrl, attachmentUrl, and pageUrl fields now return URL components rather than strings. Replace old type: absolute selections with the adapter’s query helpers, then use the matching URL helpers in your views.

For example, select an image URL with:

import {imageUrlQuery} from '@enonic/nextjs-adapter';

const imageSelection = `
  ... on media_Image {
    ${imageUrlQuery({scale: 'width(500)'})}
  }
`;

Replace getUrl(photo.imageUrl, meta) in the view with:

import {imageUrl} from '@enonic/nextjs-adapter';

<img src={imageUrl(photo.imageUrl, meta)} alt=""/>

Use mediaUrlQuery()/mediaUrl(data, meta) and attachmentUrlQuery()/attachmentUrl(data, meta) for other media and attachments. The metadata selects the starter’s /api/media proxy for draft media and the API or CDN URL for published media. The new starter already includes the proxy route; preserve it when moving your custom code. For content links, select pageUrlQuery() and render the result with pageUrl(data, meta).

Use the adapter’s richTextQuery and RichTextView for rich-text links and images. Review any custom rich-text rendering that assumes URL fields are strings. Reference files in public/ directly, for example /images/logo.svg, instead of using the removed getAsset() helper.

See Rich text, links, and media and Common API for the URL helpers.

Other adapter changes

Review custom code for these changes:

Previous usage Migration

getContentApiUrl() or UrlProcessor

These exports are removed. Use the configured API endpoint for requests and the URL helpers described above for rendered links.

MetaData.apiUrl

Metadata now exposes project, branch, and site instead. Use these fields for content context and URL helpers for links.

fetchGuillotine() or fetchFromApi() with a locale mapping argument

Both now take the endpoint URL and an optional FetchOptions argument. Supply query context through the request variables. See Server API.

Custom static-path fetching

fetchContentPathsForAllLocales() takes an optional query and count per locale; fetchContentPathsForLocale() takes a mapping, optional query, and count. Update custom calls and queries to the current signatures.

BaseMacro.renderInEditMode or RichTextView.renderMacroInEditMode

These props are removed. Macros render in editing mode as on the public site.

RichTextView.customReplacer

The callback now receives (domNode, data, meta).

MODE or custom use of IS_DEV_MODE

IS_DEV_MODE now follows NODE_ENV; the MODE variable is no longer read.

Verify the migrated site

Test the new front end against the upgraded XP stack before switching traffic:

  • Check each content type, page component, macro, and locale, including rich-text links, images, and attachments.

  • Check default-locale URLs. With en first in the mappings, /about remains the English URL, while /en/about now redirects to /about. Other locale prefixes remain.

  • Open draft content from Content Studio, test visual page editing and component refreshes, and verify that exiting Draft Mode returns to published content.

  • Test preview and draft media on the intended deployment domains as well as localhost. Local cookie behavior does not establish that cross-domain preview works.

  • Publish a change and verify revalidation, then check custom authentication, redirects, and static generation if used.

Deploy with the new project’s environment settings and confirm that XP and editors' browsers can reach its configured URL. See Deployment for connectivity requirements.


Contents

Contents