To upgrade to version 12, run the following command:
npm install next@12
# or
yarn add next@12
# or
pnpm update next@12
Middleware - If you were using Middleware prior to 12.2, please see the upgrade guide for more information.
Minimum Node.js Version - The minimum Node.js version has been bumped from 12.0.0 to 12.22.0 which is the first version of Node.js with native ES Modules support.
Minimum React Version - The minimum required React version is 17.0.2. To upgrade you can run the following command in the terminal:
npm install react@latest react-dom@latest
# or
yarn add react@latest react-dom@latest
# or
pnpm update react@latest react-dom@latest
Next.js now uses the Rust-based compiler SWC to compile JavaScript/TypeScript. This new compiler is up to 17x faster than Babel when compiling individual files and up to 5x faster Fast Refresh.
Next.js provides full backward compatibility with applications that have custom Babel configuration. All transformations that Next.js handles by default like styled-jsx and tree-shaking of getStaticProps / getStaticPaths / getServerSideProps have been ported to Rust.
When an application has a custom Babel configuration, Next.js will automatically opt-out of using SWC for compiling JavaScript/Typescript and will fall back to using Babel in the same way that it was used in Next.js 11.
Many of the integrations with external libraries that currently require custom Babel transformations will be ported to Rust-based SWC transforms in the near future. These include but are not limited to:
In order to prioritize transforms that will help you adopt SWC, please provide your .babelrc on this feedback thread.
You can opt-in to replacing Terser with SWC for minifying JavaScript up to 7x faster using a flag in next.config.js:
module.exports = {
swcMinify: true,
};
Minification using SWC is an opt-in flag to ensure it can be tested against more real-world Next.js applications before it becomes the default in Next.js 12.1. If you have feedback about minification, please leave it on this feedback thread.
On top of the Rust-based compiler we've implemented a new CSS parser based on the one used for the styled-jsx Babel transform. This new parser has improved handling of CSS and now errors when invalid CSS is used that would previously slip through and cause unexpected behavior.
Because of this change invalid CSS will throw an error during development and next build. This change only affects styled-jsx usage.
next/image changed wrapping elementnext/image now renders the <img> inside a <span> instead of <div>.
If your application has specific CSS targeting span such as .container span, upgrading to Next.js 12 might incorrectly match the wrapping element inside the <Image> component. You can avoid this by restricting the selector to a specific class such as .container span.item and updating the relevant component with that className, such as <span className="item" />.
If your application has specific CSS targeting the next/image <div> tag, for example .container div, it may not match anymore. You can update the selector .container span, or preferably, add a new <div className="wrapper"> wrapping the <Image> component and target that instead such as .container .wrapper.
The className prop is unchanged and will still be passed to the underlying <img> element.
See the documentation for more info.
Previously, Next.js used a server-sent events connection to receive HMR events. Next.js 12 now uses a WebSocket connection.
In some cases when proxying requests to the Next.js dev server, you will need to ensure the upgrade request is handled correctly. For example, in nginx you would need to add the following configuration:
location /_next/webpack-hmr {
proxy_pass http://localhost:3000/_next/webpack-hmr;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
For custom servers, such as express, you may need to use app.all to ensure the request is passed correctly, for example:
app.all('/_next/webpack-hmr', (req, res) => {
nextjsRequestHandler(req, res);
});
If you are already using webpack 5 you can skip this section.
Next.js has adopted webpack 5 as the default for compilation in Next.js 11. As communicated in the webpack 5 upgrading documentation Next.js 12 removes support for webpack 4.
If your application is still using webpack 4 using the opt-out flag, you will now see an error linking to the webpack 5 upgrading documentation.
target option deprecatedIf you do not have target in next.config.js you can skip this section.
The target option has been deprecated in favor of built-in support for tracing what dependencies are needed to run a page.
During next build, Next.js will automatically trace each page and its dependencies to determine all of the files that are needed for deploying a production version of your application.
If you are currently using the target option set to serverless, please read the documentation on how to leverage the new output.