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>.urlto the new front-end URL. Generate a new shared secret fornextjs.<name>.secretand use the same value forENONIC_API_TOKENin 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_NAMEandENONIC_MAPPINGS, keeping the same default locale unless you intend to change your public URLs. SetENONIC_API_TOKENto the new secret configured incom.enonic.app.nextxp.cfg, storing it in.env.localor deployment secrets.Update
ENONIC_APIto the XP API root:# v5 ENONIC_API=http://localhost:8080/site # v6 ENONIC_API=http://localhost:8080/apiRemove 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_CDNandENONIC_ADMINagainst 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 |
|---|---|
|
|
These exports are removed. Use the configured API endpoint for requests and the URL helpers described above for rendered links. |
|
|
Metadata now exposes |
|
|
Both now take the endpoint URL and an optional |
|
Custom static-path fetching |
|
|
|
These props are removed. Macros render in editing mode as on the public site. |
|
|
The callback now receives |
|
|
|
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
enfirst in the mappings,/aboutremains the English URL, while/en/aboutnow 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.