The Next.js Compiler, written in Rust using [SWC](http://swc.rs/), allows Next.js to transform and minify your JavaScript code for production. This replaces Babel for individual files and Terser for minifying output bundles.
Compilation using the Next.js Compiler is 17x faster than Babel and enabled by default since Next.js version 12. If you have an existing Babel configuration or are using [unsupported features](#unsupported-features), your application will opt-out of the Next.js Compiler and continue using Babel.
## Why SWC?
[SWC](http://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools.
SWC can be used for compilation, minification, bundling, and more – and is designed to be extended. It's something you can call to perform code transformations (either built-in or custom). Running those transformations happens through higher-level tools like Next.js.
We chose to build on SWC for a few reasons:
- **Extensibility:** SWC can be used as a Crate inside Next.js, without having to fork the library or workaround design constraints.
- **Performance:** We were able to achieve ~3x faster Fast Refresh and ~5x faster builds in Next.js by switching to SWC, with more room for optimization still in progress.
- **WebAssembly:** Rust's support for WASM is essential for supporting all possible platforms and taking Next.js development everywhere.
- **Community:** The Rust community and ecosystem are amazing and still growing.
Currently, only the `ssr` and `displayName` transforms have been implemented. These two transforms are the main requirement for using `styled-components` in Next.js.
### Jest
Jest support not only includes the transformation previously provided by Babel, but also simplifies configuring Jest together with Next.js including:
- Auto mocking of `.css`, `.module.css` (and their `.scss` variants), and image imports
- Automatically sets up `transform` using SWC
- Loading `.env` (and all variants) into `process.env`
- Ignores `node_modules` from test resolving and transforms
- Ignoring `.next` from test resolving
- Loads `next.config.js` for flags that enable experimental SWC transforms
First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jest.config.js` file:
```js
// jest.config.js
const nextJest = require('next/jest')
// Providing the path to your Next.js app which will enable loading next.config.js and .env files
NOTE: In Next.js all JavaScript files in `pages` directory are considered routes. So, for `relay-compiler` you'll need to specify `artifactDirectory` configuration settings outside of the `pages`, otherwise `relay-compiler` will generate files next to the source file in the `__generated__` directory, and this file will be considered a route, which will break production builds.
Next.js will automatically detect `experimentalDecorators` in `jsconfig.json` or `tsconfig.json`. Legacy decorators are commonly used with older versions of libraries like `mobx`.
This flag is only supported for compatibility with existing applications. We do not recommend using legacy decorators in new applications.
First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file:
Next.js will automatically detect `jsxImportSource` in `jsconfig.json` or `tsconfig.json` and apply that. This is commonly used with libraries like Theme UI.
First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file:
While the minifier is experimental, we are making the following options available for debugging purposes. They will not be available once the minifier is made stable.
```js
// next.config.js
module.exports = {
experimental: {
swcMinifyDebugOptions: {
compress: {
defaults: true,
side_effects: false,
},
},
},
swcMinify: true,
}
```
If your app works with the options above, it means `side_effects` is the problematic option.
See [the SWC documentation](https://swc.rs/docs/configuration/minification#jscminifycompress) for detailed options.
Allows to modularize imports, similar to [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports).
Transforms member style imports:
```js
import { Row, Grid as MyGrid } from 'react-bootstrap'
import { merge } from 'lodash'
```
...into default style imports:
```js
import Row from 'react-bootstrap/lib/Row'
import MyGrid from 'react-bootstrap/lib/Grid'
import merge from 'lodash/merge'
```
Config for the above transform:
```js
// next.config.js
module.exports = {
experimental: {
modularizeImports: {
'react-bootstrap': {
transform: 'react-bootstrap/lib/{{member}}',
},
lodash: {
transform: 'lodash/{{member}}',
},
},
},
}
```
Advanced transformations:
- Using regular expressions
Similar to `babel-plugin-transform-imports`, but the transform is templated with [handlebars](https://docs.rs/handlebars) and regular expressions are in Rust [regex](https://docs.rs/regex/latest/regex/) crate's syntax.
import { Header, Footer } from 'my-library/components/App'
```
To become:
```js
import MyModule from 'my-library/MyModule'
import App from 'my-library/components/App'
import Header from 'my-library/components/App/Header'
import Footer from 'my-library/components/App/Footer'
```
- Handlebars templating
This transform uses [handlebars](https://docs.rs/handlebars) to template the replacement import path in the `transform` field. These variables and helper functions are available:
1.`matches`: Has type `string[]`. All groups matched by the regular expression. `matches.[0]` is the full match.
2.`member`: Has type `string`. The name of the member import.
3.`lowerCase`, `upperCase`, `camelCase`: Helper functions to convert a string to lower, upper or camel cases.
You can generate SWC's internal transform traces as chromium's [trace event format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview?mode=html#%21=).
```js
// next.config.js
module.exports = {
experimental: {
swcTraceProfiling: true,
},
}
```
Once enabled, swc will generate trace named as `swc-trace-profile-${timestamp}.json` under `.next/`. Chromium's trace viewer (chrome://tracing/, https://ui.perfetto.dev/), or compatible flamegraph viewer (https://www.speedscope.app/) can load & visualize generated traces.
### Experimental SWC plugin support
You can configure swc's transform to use SWC's experimental plugin support written in wasm to customize transformation behavior.
```js
// next.config.js
module.exports = {
experimental: {
swcPlugins: [
['plugin', {
..pluginOptions
}]
]
}
}
```
`swcPlugins` accepts an array of tuples for configuring plugins. A tuple for the plugin contains the path to the plugin and an object for plugin configuration. The path to the plugin can be an npm module package name or an absolute path to the `.wasm` binary itself.
When your application has a `.babelrc` file, Next.js will automatically fall back to using Babel for transforming individual files. This ensures backwards compatibility with existing applications that leverage custom Babel plugins.
If you're using a custom Babel setup, [please share your configuration](https://github.com/vercel/next.js/discussions/30174). We're working to port as many commonly used Babel transformations as possible, as well as supporting plugins in the future.