Netlify Docs
Ask Netlify

Contact

Frameworks /Framework support /Next.js /

Next.js on Netlify

Netlify Next.js adapter v5 test status

Netlify’s Next.js adapter automatically configures Netlify sites to enable key functionality, including cache control, on-demand revalidation, and image optimization.

Next.js adapter v5

The information on this page applies to Next.js version 13.5 or later, running with Netlify’s Next.js adapter v5. For earlier Next.js versions, go to the legacy runtime docs.

# OpenNext Netlify adapter

Netlify’s current Next.js adapter is maintained in the open as part of the OpenNext initiative. For information on working with the latest adapter, visit the Netlify docs on OpenNext.

# Upgrade to the latest adapter

We actively maintain the v5 adapter to support all Next.js versions starting from version 13.5.

Unless you’ve manually installed a specific version of the adapter in your package.json, you never need to manually update it. We will automatically use the latest version on each site build for you.

Automatic installation preferred

We recommend that you remove the package from your package.json and netlify.toml files to allow Netlify to automatically update the adapter when new versions are available. This gives you the benefit of always having the latest features and fixes. Note that we won't provide automatic updates for breaking changes.

# Upgrade from v4.x to v5.x

  1. If your site is pinned to an earlier runtime version, upgrade Next.js to 13.5 or later, and Node.js to 18 or later.

  2. Address the breaking changes noted below.

  3. Change the package name in your package.json and netlify.toml from @netlify/plugin-nextjs to @opennextjs/netlify, and ensure the version is at least v5.9.

# v5 breaking changes

Before upgrading to v5, review the following breaking changes:

# Known issues when upgrading

If you opt in through the Netlify UI without the correct Next.js or Node version, the following message will appear in your deploy log:

To upgrade this plugin, please uninstall and re-install it from the Netlify plugins directory

This deploy log message is incorrect. Instead of uninstalling and reinstalling the plugin, you need to update your Next.js to at least version 13.5 and Node.js to at least version 18.

# Pin a specific adapter version to your site

If you find that you need to return to a specific version of the Next.js adapter or runtime, you can pin that version to your site.

We recommend that you don’t pin the adapter version. We actively maintain the v5 adapter to support all Next.js versions starting from version 13.5 and, if you don’t pin the version, we will automatically update the adapter to the latest version on each site build for you.

  1. Install your desired version of the @netlify/plugin-nextjs package:

      npm i @netlify/plugin-nextjs@1.2.3

  2. In your netlify.toml, add:

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

# More resources

←