eeb87fa21e
add (Experimental) to title for `unstable_rethrow` to match all other `unstable_` functions ### Fixing a bug - Related issues linked using `fixes #66966` <img width="1287" alt="image" src="https://github.com/vercel/next.js/assets/147033096/5a790b63-30c9-4605-b0e8-73899afb8e59"> ## For Maintainers `unstable_rethrow` has a different title scheme compared to all other `unstable_` functions this is just a quick fix for this since it was bugging me. Closes NEXT-66966 Fixes #66966 --------- Co-authored-by: Sam Ko <sam@vercel.com>
321 lines
13 KiB
Text
321 lines
13 KiB
Text
---
|
||
title: Next.js Compiler
|
||
description: Next.js Compiler, written in Rust, which transforms and minifies your Next.js application.
|
||
---
|
||
|
||
The Next.js Compiler, written in Rust using [SWC](https://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](https://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.
|
||
|
||
## Supported Features
|
||
|
||
### Styled Components
|
||
|
||
We're working to port `babel-plugin-styled-components` to the Next.js Compiler.
|
||
|
||
First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file:
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
styledComponents: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
For advanced use cases, you can configure individual properties for styled-components compilation.
|
||
|
||
> Note: `ssr` and `displayName` transforms are the main requirement for using `styled-components` in Next.js.
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
// see https://styled-components.com/docs/tooling#babel-plugin for more info on the options.
|
||
styledComponents: {
|
||
// Enabled by default in development, disabled in production to reduce file size,
|
||
// setting this will override the default for all environments.
|
||
displayName?: boolean,
|
||
// Enabled by default.
|
||
ssr?: boolean,
|
||
// Enabled by default.
|
||
fileName?: boolean,
|
||
// Empty by default.
|
||
topLevelImportPaths?: string[],
|
||
// Defaults to ["index"].
|
||
meaninglessFileNames?: string[],
|
||
// Enabled by default.
|
||
minify?: boolean,
|
||
// Enabled by default.
|
||
transpileTemplateLiterals?: boolean,
|
||
// Empty by default.
|
||
namespace?: string,
|
||
// Disabled by default.
|
||
pure?: boolean,
|
||
// Enabled by default.
|
||
cssProp?: boolean,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### Jest
|
||
|
||
The Next.js Compiler transpiles your tests and 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 filename="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
|
||
const createJestConfig = nextJest({ dir: './' })
|
||
|
||
// Any custom config you want to pass to Jest
|
||
const customJestConfig = {
|
||
setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
|
||
}
|
||
|
||
// createJestConfig is exported in this way to ensure that next/jest can load the Next.js configuration, which is async
|
||
module.exports = createJestConfig(customJestConfig)
|
||
```
|
||
|
||
### Relay
|
||
|
||
To enable [Relay](https://relay.dev/) support:
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
relay: {
|
||
// This should match relay.config.js
|
||
src: './',
|
||
artifactDirectory: './__generated__',
|
||
language: 'typescript',
|
||
eagerEsModules: false,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
> **Good to know**: 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.
|
||
|
||
### Remove React Properties
|
||
|
||
Allows to remove JSX properties. This is often used for testing. Similar to `babel-plugin-react-remove-properties`.
|
||
|
||
To remove properties matching the default regex `^data-test`:
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
reactRemoveProperties: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
To remove custom properties:
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
// The regexes defined here are processed in Rust so the syntax is different from
|
||
// JavaScript `RegExp`s. See https://docs.rs/regex.
|
||
reactRemoveProperties: { properties: ['^data-custom$'] },
|
||
},
|
||
}
|
||
```
|
||
|
||
### Remove Console
|
||
|
||
This transform allows for removing all `console.*` calls in application code (not `node_modules`). Similar to `babel-plugin-transform-remove-console`.
|
||
|
||
Remove all `console.*` calls:
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
removeConsole: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
Remove `console.*` output except `console.error`:
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
compiler: {
|
||
removeConsole: {
|
||
exclude: ['error'],
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### Legacy Decorators
|
||
|
||
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:
|
||
|
||
```js
|
||
{
|
||
"compilerOptions": {
|
||
"experimentalDecorators": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### importSource
|
||
|
||
Next.js will automatically detect `jsxImportSource` in `jsconfig.json` or `tsconfig.json` and apply that. This is commonly used with libraries like [Theme UI](https://theme-ui.com).
|
||
|
||
First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file:
|
||
|
||
```js
|
||
{
|
||
"compilerOptions": {
|
||
"jsxImportSource": "theme-ui"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Emotion
|
||
|
||
We're working to port `@emotion/babel-plugin` to the Next.js Compiler.
|
||
|
||
First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file:
|
||
|
||
```js filename="next.config.js"
|
||
|
||
module.exports = {
|
||
compiler: {
|
||
emotion: boolean | {
|
||
// default is true. It will be disabled when build type is production.
|
||
sourceMap?: boolean,
|
||
// default is 'dev-only'.
|
||
autoLabel?: 'never' | 'dev-only' | 'always',
|
||
// default is '[local]'.
|
||
// Allowed values: `[local]` `[filename]` and `[dirname]`
|
||
// This option only works when autoLabel is set to 'dev-only' or 'always'.
|
||
// It allows you to define the format of the resulting label.
|
||
// The format is defined via string where variable parts are enclosed in square brackets [].
|
||
// For example labelFormat: "my-classname--[local]", where [local] will be replaced with the name of the variable the result is assigned to.
|
||
labelFormat?: string,
|
||
// default is undefined.
|
||
// This option allows you to tell the compiler what imports it should
|
||
// look at to determine what it should transform so if you re-export
|
||
// Emotion's exports, you can still use transforms.
|
||
importMap?: {
|
||
[packageName: string]: {
|
||
[exportName: string]: {
|
||
canonicalImport?: [string, string],
|
||
styledBaseImport?: [string, string],
|
||
}
|
||
}
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### Minification
|
||
|
||
Next.js' swc compiler is used for minification by default since v13. This is 7x faster than Terser.
|
||
|
||
If Terser is still needed for any reason this can be configured.
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
swcMinify: false,
|
||
}
|
||
```
|
||
|
||
### Module Transpilation
|
||
|
||
Next.js can automatically transpile and bundle dependencies from local packages (like monorepos) or from external dependencies (`node_modules`). This replaces the `next-transpile-modules` package.
|
||
|
||
```js filename="next.config.js"
|
||
module.exports = {
|
||
transpilePackages: ['@acme/ui', 'lodash-es'],
|
||
}
|
||
```
|
||
|
||
### Modularize Imports
|
||
|
||
This option has been superseded by [`optimizePackageImports`](/docs/app/api-reference/next-config-js/optimizePackageImports) in Next.js 13.5. We recommend upgrading to use the new option that does not require manual configuration of import paths.
|
||
|
||
## Experimental Features
|
||
|
||
### SWC Trace profiling
|
||
|
||
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 filename="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.
|
||
|
||
### SWC Plugins (experimental)
|
||
|
||
You can configure swc's transform to use SWC's experimental plugin support written in wasm to customize transformation behavior.
|
||
|
||
```js filename="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.
|
||
|
||
## Unsupported Features
|
||
|
||
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.
|
||
|
||
## Version History
|
||
|
||
| Version | Changes |
|
||
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `v13.1.0` | [Module Transpilation](https://nextjs.org/blog/next-13-1#built-in-module-transpilation-stable) and [Modularize Imports](https://nextjs.org/blog/next-13-1#import-resolution-for-smaller-bundles) stable. |
|
||
| `v13.0.0` | SWC Minifier enabled by default. |
|
||
| `v12.3.0` | SWC Minifier [stable](https://nextjs.org/blog/next-12-3#swc-minifier-stable). |
|
||
| `v12.2.0` | [SWC Plugins](#swc-plugins-experimental) experimental support added. |
|
||
| `v12.1.0` | Added support for Styled Components, Jest, Relay, Remove React Properties, Legacy Decorators, Remove Console, and jsxImportSource. |
|
||
| `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12). |
|