Add docs for the Next.js Compiler written in Rust (leveraging SWC) (#…

…31485)

Co-authored-by: Steven <[email protected]>
Co-authored-by: Lee Robinson <[email protected]>
Co-authored-by: Lee Robinson <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

docs/advanced-features/compiler.md

@@ -0,0 +1,131 @@
+---
+description: Learn about the Next.js Compiler, written in Rust, which transforms and minifies your Next.js application.
+---
+
+# Next.js Compiler
+
+<details open>
+  <summary><b>Version History</b></summary>
+
+| Version   | Changes                                                         |
+| --------- | --------------------------------------------------------------- |
+| `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12). |
+
+</details>
+
+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.
+
+## Experimental Features
+
+### Minification
+
+You can opt-in to using the Next.js compiler for minification. This is 7x faster than Terser.
+
+```js
+// next.config.js
+
+module.exports = {
+  swcMinify: true,
+}
+```
+
+If you have feedback about `swcMinify`, please share it on the [feedback discussion](https://github.com/vercel/next.js/discussions/30237).
+
+### 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
+// next.config.js
+
+module.exports = {
+  experimental: {
+    // ssr and displayName are configured by default
+    styledComponents: true,
+  },
+}
+```
+
+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
+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)
+```
+
+### Legacy Decorators
+
+Next.js will automatically detect `experimentalDecorators` in `jsconfig.json` or `tsconfig.json` and apply that. This is 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.
+
+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": true
+  }
+}
+```
+
+## 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.

docs/manifest.json

@@ -128,6 +128,10 @@
         {
           "title": "Advanced Features",
           "routes": [
+            {
+              "title": "Next.js Compiler",
+              "path": "/docs/advanced-features/compiler.md"
+            },
             {
               "title": "Preview Mode",
               "path": "/docs/advanced-features/preview-mode.md"