Upgrading

Dependencies: Update @enonic/nextjs-adapter to ^6.0.0. On the XP side, install Guillotine 9 and Next.XP app 6.

ENONIC_API: Point it to the XP API root instead of the /site endpoint:

# Before (v5.x)
ENONIC_API=http://localhost:8080/site

# After (v6.x)
ENONIC_API=http://localhost:8080/api

Guillotine 9 query syntax: Pass siteKey, project, and branch to the guillotine() field:

# Before (v5.x)
query($path:ID!) {
  guillotine {
    get(key: $path) { ... }
  }
}

# After (v6.x)
query {
  guillotine(siteKey: $siteKey, branch: $branch, project: $project) {
    get(key: $path) { ... }
  }
}

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

export function commonVariables(vars: GlobalVariables) {
    return vars;
}

Media and page URLs: imageUrl, mediaUrl, attachmentUrl, and pageUrl return objects in Guillotine 9. Query them with the adapter’s helpers and render them with the matching functions, replacing getUrl(), getAsset(), and type: absolute:

// Before (v5.x)
imageUrl: imageUrl(type: absolute, scale: "width(500)")
<img src={getUrl(photo.imageUrl, meta)}/>

// After (v6.x)
${imageUrlQuery({scale: 'width(500)'})}
<img src={imageUrl(photo.imageUrl)}/>

${pageUrlQuery()}
<Link href={pageUrl(parent.pageUrl, meta)}>Back</Link>

Proxy: Replace src/proxy.ts with the starter’s version. It validates the xp parameter, enables draft mode through /api/preview, rewrites prefix-less URLs to the internal default-locale route, and redirects /<default locale>/…​ to /…​. URLs without the default-locale prefix were already supported in v5; redirecting explicitly prefixed URLs is new in v6. For example, with en as the default, /about continues to work and /en/about now redirects to /about.

Encrypted API routes: Replace the token check with blob validation in /api/preview and /api/revalidate, and copy src/utils.ts from the starter:

// Before (v5.x)
import {validateToken} from '../../../utils';

// After (v6.x)
import {validateBlob} from '../../../utils';

/api/mappings: Add the route from the starter. It returns localizeMappings(MAPPINGS, mapping) for the project in the blob.

/api/renderable: Delete the route. It is no longer called.

next.config.js: Add env.BUILD_ID and the CORS headers from the starter. The allowed origin is derived from the optional ENONIC_ADMIN variable, falling back to the origin of ENONIC_API:

const config = {
    env: {
        BUILD_ID: Date.now().toString(36),
    },
    // ...
};

// response headers for '/:path*'
{key: 'Access-Control-Allow-Origin', value: xpOrigin},
{key: 'Access-Control-Allow-Credentials', value: 'true'},
{key: 'Access-Control-Allow-Methods', value: 'GET, POST, PUT, DELETE, PATCH, OPTIONS'}

Adapter API changes:

XP configuration: Remove any contentSecurityPolicy.header entries added for Next.XP to com.enonic.app.contentstudio.cfg. The Next.XP app now allows its configured origins automatically, but only explicitly configured URLs in production mode. com.enonic.app.nextxp.cfg keeps the same property format. Site setup is unchanged: the Next.XP app must be added to the XP site with its front-end configuration selected.

Adapter upgrade: Update @enonic/nextjs-adapter to ^5.0.0.

Enonic XP 8: The back-end must run Enonic XP 8, with application schemas in the YAML format under src/main/resources/cms/. Guillotine 8 is used with XP 8 — existing queries work unchanged. Note that media links in rich text now use the /_/media:image/ and /_/media:attachment/ URL format, which requires adapter v5.

Framework upgrades: Next.js 16 and React 19 are now required.

Adapter upgrade: Update @enonic/nextjs-adapter to ^4.0.0.

Middleware replaced by proxy: Rename src/middleware.ts to src/proxy.ts, following the Next.js 16 convention.

Next.js 16 async params: Route params are now Promise and must be awaited:

// Before (v3.x)
export type PageProps = {
    locale: string,
    contentPath: string[],
}
export default async function Page({params}: { params: PageProps }) {
    const {locale, contentPath} = params;

// After (v4.x)
export type PageProps = {
    locale: string,
    contentPath?: string[],
}
export default async function Page({params}: { params: Promise<PageProps> }) {
    const resolvedParams = await params;

ESLint flat config: Migrate from .eslintrc to eslint.config.mjs:

import nextVitals from 'eslint-config-next/core-web-vitals'
import {defineConfig, globalIgnores} from 'eslint/config'

const eslintConfig = defineConfig([
    ...nextVitals,
    {
        rules: {
            "@next/next/no-img-element": "off",
            "eol-last": "warn"
        }
    },
    globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts'])
])

export default eslintConfig

Default port change: npm run start no longer forces port 4242 — production now runs on the default port 3000.

You need to use Next.js app router to be able to use v3.x. See upgrade instructions from pages router here.

_renderable page is now an API route at src/api/renderable/route.ts.

@enonic/nextjs-adapter methods renamed:

@enonic/nextjs-adapter method signature changes:

@enonic/nextjs-adapter exports rearranged:

ENONIC_PROJECTS environmental variable change:

ENONIC_PROJECTS -> ENONIC_MAPPINGS

ENONIC_MAPPINGS=<lang>:<repo-name>/site/path[,<lang>:<repo-name>/site/path,...]

next.config.js config changes:

i18n: {
    locales: ['en', 'no'],
    defaultLocale: 'en',
}

config.resolve.alias = {
    ...config.resolve.alias,
    "@phrases": path.resolve(__dirname, "./src/phrases"),
}

Add src/phrases folder to your project root. This folder should contain static translations for every language from ENONIC_MAPPINGS env var in the following format: src/phrases/<lang>.json

src/phrases/en.json
src/phrases/no.json

Middleware file has been updated to support new i18n config. If you have custom proxy, you need to update it to support new i18n config.