Docs Developer Site
Developer Learn Next.js website next Release Upgrading

Upgrading

Contents

Guillotine application

Guillotine version 7 is required if you need to modify graphql schema in your application.

Upgrading from v3.x

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

    See Next.js upgrade guide and React 19 migration guide.

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

    The Guillotine query syntax and ENONIC_API URL format are unchanged.

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

    If you have custom middleware logic, migrate it to the new proxy pattern.

  4. 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;

  5. 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

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

    If you relied on port 4242, update your com.enonic.app.nextxp.cfg and any reverse-proxy configuration accordingly.

Upgrading from v2.x

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

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

  3. @enonic/nextjs-adapter methods renamed:

    • getLocaleProjectConfig() → getLocaleMapping()

    • getProjectLocaleConfigById → getLocaleMappingById()

  4. @enonic/nextjs-adapter method signature changes:

    • fetchFromApi method changed to :

      fetchFromApi(
   apiUrl: string,
   projectConfig: ProjectLocaleConfig,
   options?: FetchOptions): Promise<GuillotineResponseJson>

    • fetchGuillotine method signature changes:

      fetchGuillotine(
   contentApiUrl: string,
   projectConfig: ProjectLocaleConfig,
   options?: FetchOptions): Promise<GuillotineResult>

  5. @enonic/nextjs-adapter exports rearranged:

    Exports working both on the server and client sides are now available from @enonic/nextjs-adapter package root. Client-only exports are available from @enonic/nextjs-adapter/client package. Server-only exports are available from @enonic/nextjs-adapter/server package. Views are available at @enonic/nextjs-adapter/views/<ViewName>.

  6. ENONIC_PROJECTS environmental variable change:

    ENONIC_PROJECTS -> ENONIC_MAPPINGS
    Language is now required for every project config:
    ENONIC_MAPPINGS=<lang>:<repo-name>/site/path[,<lang>:<repo-name>/site/path,...]
    First config in the list is used as default.

  7. next.config.js config changes:

    Remove i18n block from next.js config:
    i18n: {
    locales: ['en', 'no'],
    defaultLocale: 'en',
}
    Add phrases block to webpack config:
    config.resolve.alias = {
    ...config.resolve.alias,
    "@phrases": path.resolve(__dirname, "./src/phrases"),
}

  8. 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

  9. 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.

Contents

Contents