Netlify Docs
Ask Netlify

Contact

Frameworks /Framework support /Next.js /Legacy Runtime /

Upgrading or reverting the Next.js adapter

Netlify’s current adapter for Next.js is built as part of the OpenNext initiative and supports all Next.js versions starting from v13.5 and above. The adapter is automatically applied at build time unless you have explicitly pinned a version in your configuration. We strongly recommend using the latest adapter version to benefit from ongoing improvements and fixes.

# When to upgrade

The latest adapter version is automatically applied during your build unless you've explicitly pinned an older version. You should consider upgrading when:

  • You are moving to a newer version of Next.js (v13.5+)
  • You want access to new features (App Router, Server Actions, etc.)
  • You are resolving known issues addressed in newer versions

# Upgrade to the latest adapter

Before upgrading, consider the following:

  • Netlify forms: If your site uses Netlify Forms, changes may be required. See the Forms compatibility guide.
  • Advanced API routes: Sites using background or scheduled functions via Next.js API routes must convert these to regular Netlify Functions. See examples in the docs.

To upgrade to the latest adapter:

  1. Update Next.js and Node versions:

    • Next.js: v13.5 or later
    • Node.js: v18 or later

  2. Remove legacy plugin references (if any) in your package.json file by finding @netlify/plugin-nextjs:

    {
  "devDependencies": {
    "@netlify/plugin-nextjs": "remove this"
  }
}

  3. Remove any plugin configuration for @netlify/plugin-nextjs in your netlify.toml:

    [[plugins]]
package = "@netlify/plugin-nextjs"

  4. To finalize the updates, trigger a new deploy. The latest version of the adapter will be applied automatically. You can confirm this in the build logs.

# Reverting to an older adapter version

To pin a specific version of the adapter:

  1. Install the version you want in package.json:

    npm install @netlify/plugin-nextjs@<version>

  2. Add the plugin to your netlify.toml:

    [[plugins]]
package = "@netlify/plugin-nextjs"

Note this approach reverts your site to the legacy plugin system. You'll be opting out of automatic updates and newer architecture improvements maintained through OpenNext.

← Next.js redirects and rewrites →