Unverified Commit 3f224515 authored by Tim Neutkens's avatar Tim Neutkens Committed by GitHub

Update upgrade docs (#30265)

Co-authored-by: 's avatarLee Robinson <me@leerob.io>
Co-authored-by: 's avatarSteven <steven@ceriously.com>
parent 149353b8
......@@ -4,6 +4,66 @@ description: Learn how to upgrade Next.js.
# Upgrade Guide
## Upgrading from 11 to 12
### SWC replacing Babel
Next.js now uses Rust-based compiler [SWC](https://swc.rs/) 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 backwards compatibility with applications that have [custom Babel configuration](https://nextjs.org/docs/advanced-features/customizing-babel-config). 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:
- Styled Components
- Emotion
- Relay
In order to prioritize transforms that will help you adopt SWC, please provide your `.babelrc` on [the feedback thread](https://github.com/vercel/next.js/discussions/30174).
### SWC replacing Terser for minification
You can opt-in to replacing Terser with SWC for minifying JavaScript up to 7x faster using a flag in `next.config.js`:
```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 [the feedback thread](https://github.com/vercel/next.js/discussions/30237).
### `next/image` changed wrapping element
`next/image` now renders the `<img>` inside a `<span>` instead of `<div>`.
If your application has specific CSS targeting span, for example `.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 you 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](https://nextjs.org/docs/basic-features/image-optimization#styling) for more info.
### Webpack 4 support has been removed
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](https://nextjs.org/docs/messages/webpack5) 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](https://nextjs.org/docs/messages/webpack5).
### `target` option deprecated
If 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](https://nextjs.org/docs/advanced-features/output-file-tracing).
## Upgrading from version 10 to 11
### Upgrade React version to latest
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment