|
| 1 | +--- |
| 2 | +description: Learn about the Next.js Compiler, written in Rust, which transforms and minifies your Next.js application. |
| 3 | +--- |
| 4 | + |
| 5 | +# Next.js Compiler |
| 6 | + |
| 7 | +<details open> |
| 8 | + <summary><b>Version History</b></summary> |
| 9 | + |
| 10 | +| Version | Changes | |
| 11 | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------- | |
| 12 | +| `v12.1.0` | Added support for Styled Components, Jest, Relay, Remove React Properties, Legacy Decorators, Remove Console, and jsxImportSource. | |
| 13 | +| `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12). | |
| 14 | + |
| 15 | +</details> |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +<!-- textlint-disable --> |
| 22 | +## Why SWC? |
| 23 | + |
| 24 | +[SWC](http://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools. |
| 25 | + |
| 26 | +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. |
| 27 | + |
| 28 | +We chose to build on SWC for a few reasons: |
| 29 | + |
| 30 | +- **Extensibility:** SWC can be used as a Crate inside Next.js, without having to fork the library or workaround design constraints. |
| 31 | +- **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. |
| 32 | +- **WebAssembly:** Rust's support for WASM is essential for supporting all possible platforms and taking Next.js development everywhere. |
| 33 | +- **Community:** The Rust community and ecosystem are amazing and still growing. |
| 34 | + |
| 35 | +## Supported Features |
| 36 | + |
| 37 | +### Styled Components |
| 38 | + |
| 39 | +We're working to port `babel-plugin-styled-components` to the Next.js Compiler. |
| 40 | + |
| 41 | +First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file: |
| 42 | + |
| 43 | +```js |
| 44 | +// next.config.js |
| 45 | + |
| 46 | +module.exports = { |
| 47 | + compiler: { |
| 48 | + // ssr and displayName are configured by default |
| 49 | + styledComponents: true, |
| 50 | + }, |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +Currently, only the `ssr` and `displayName` transforms have been implemented. These two transforms are the main requirement for using `styled-components` in Next.js. |
| 55 | + |
| 56 | +### Jest |
| 57 | + |
| 58 | +Jest support not only includes the transformation previously provided by Babel, but also simplifies configuring Jest together with Next.js including: |
| 59 | + |
| 60 | +- Auto mocking of `.css`, `.module.css` (and their `.scss` variants), and image imports |
| 61 | +- Automatically sets up `transform` using SWC |
| 62 | +- Loading `.env` (and all variants) into `process.env` |
| 63 | +- Ignores `node_modules` from test resolving and transforms |
| 64 | +- Ignoring `.next` from test resolving |
| 65 | +- Loads `next.config.js` for flags that enable experimental SWC transforms |
| 66 | + |
| 67 | +First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jest.config.js` file: |
| 68 | + |
| 69 | +```js |
| 70 | +// jest.config.js |
| 71 | +const nextJest = require('next/jest') |
| 72 | + |
| 73 | +// Providing the path to your Next.js app which will enable loading next.config.js and .env files |
| 74 | +const createJestConfig = nextJest({ dir }) |
| 75 | + |
| 76 | +// Any custom config you want to pass to Jest |
| 77 | +const customJestConfig = { |
| 78 | + setupFilesAfterEnv: ['<rootDir>/jest.setup.js'], |
| 79 | +} |
| 80 | + |
| 81 | +// createJestConfig is exported in this way to ensure that next/jest can load the Next.js configuration, which is async |
| 82 | +module.exports = createJestConfig(customJestConfig) |
| 83 | +``` |
| 84 | + |
| 85 | +### Relay |
| 86 | + |
| 87 | +To enable [Relay](https://relay.dev/) support: |
| 88 | + |
| 89 | +```js |
| 90 | +// next.config.js |
| 91 | +module.exports = { |
| 92 | + compiler: { |
| 93 | + relay: { |
| 94 | + // This should match relay.config.js |
| 95 | + src: './', |
| 96 | + artifactDirectory: './__generated__', |
| 97 | + language: 'typescript', |
| 98 | + }, |
| 99 | + }, |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +<!-- textlint-disable --> |
| 104 | +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. |
| 105 | + |
| 106 | +### Remove React Properties |
| 107 | + |
| 108 | +Allows to remove JSX properties. This is often used for testing. Similar to `babel-plugin-react-remove-properties`. |
| 109 | + |
| 110 | +To remove properties matching the default regex `^data-test`: |
| 111 | + |
| 112 | +```js |
| 113 | +// next.config.js |
| 114 | +module.exports = { |
| 115 | + compiler: { |
| 116 | + reactRemoveProperties: true, |
| 117 | + }, |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +To remove custom properties: |
| 122 | + |
| 123 | +```js |
| 124 | +// next.config.js |
| 125 | +module.exports = { |
| 126 | + compiler: { |
| 127 | + // The regexes defined here are processed in Rust so the syntax is different from |
| 128 | + // JavaScript `RegExp`s. See https://docs.rs/regex. |
| 129 | + reactRemoveProperties: { properties: ['^data-custom$'] }, |
| 130 | + }, |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +### Remove Console |
| 135 | + |
| 136 | +This transform allows for removing all `console.*` calls in application code (not `node_modules`). Similar to `babel-plugin-transform-remove-console`. |
| 137 | + |
| 138 | +Remove all `console.*` calls: |
| 139 | + |
| 140 | +```js |
| 141 | +// next.config.js |
| 142 | +module.exports = { |
| 143 | + compiler: { |
| 144 | + removeConsole: true, |
| 145 | + }, |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +Remove `console.*` output except `console.error`: |
| 150 | + |
| 151 | +```js |
| 152 | +// next.config.js |
| 153 | +module.exports = { |
| 154 | + compiler: { |
| 155 | + removeConsole: { |
| 156 | + exclude: ['error'], |
| 157 | + }, |
| 158 | + }, |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +### Legacy Decorators |
| 163 | + |
| 164 | +Next.js will automatically detect `experimentalDecorators` in `jsconfig.json` or `tsconfig.json`. Legacy decorators are commonly used with older versions of libraries like `mobx`. |
| 165 | + |
| 166 | +This flag is only supported for compatibility with existing applications. We do not recommend using legacy decorators in new applications. |
| 167 | + |
| 168 | +First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file: |
| 169 | + |
| 170 | +```js |
| 171 | +{ |
| 172 | + "compilerOptions": { |
| 173 | + "experimentalDecorators": true |
| 174 | + } |
| 175 | +} |
| 176 | +``` |
| 177 | + |
| 178 | +### importSource |
| 179 | + |
| 180 | +Next.js will automatically detect `jsxImportSource` in `jsconfig.json` or `tsconfig.json` and apply that. This is commonly used with libraries like Theme UI. |
| 181 | + |
| 182 | +First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file: |
| 183 | + |
| 184 | +```js |
| 185 | +{ |
| 186 | + "compilerOptions": { |
| 187 | + "jsxImportSource": 'preact' |
| 188 | + } |
| 189 | +} |
| 190 | +``` |
| 191 | + |
| 192 | +## Experimental Features |
| 193 | + |
| 194 | +### Minification |
| 195 | + |
| 196 | +You can opt-in to using the Next.js compiler for minification. This is 7x faster than Terser. |
| 197 | + |
| 198 | +```js |
| 199 | +// next.config.js |
| 200 | + |
| 201 | +module.exports = { |
| 202 | + swcMinify: true, |
| 203 | +} |
| 204 | +``` |
| 205 | + |
| 206 | +If you have feedback about `swcMinify`, please share it on the [feedback discussion](https://github.com/vercel/next.js/discussions/30237). |
| 207 | + |
| 208 | +## Unsupported Features |
| 209 | + |
| 210 | +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. |
| 211 | + |
| 212 | +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. |
0 commit comments