Chore/stable swc compiler options

docs/advanced-features/compiler.md

@@ -7,9 +7,10 @@ description: Learn about the Next.js Compiler, written in Rust, which transforms
 <details open>
   <summary><b>Version History</b></summary>
 
-| Version   | Changes                                                         |
-| --------- | --------------------------------------------------------------- |
-| `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12). |
+| Version   | Changes                                                                                                                      |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `v12.1.0` | Added support for Styled Components, Relay, Remove React Properties, Legacy Decorators, Remove Console, and jsxImportSource. |
+| `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12).                                                              |
 
 </details>
 
@@ -30,21 +31,7 @@ We chose to build on SWC for a few reasons:
 - **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).
+## Supported Features
 
 ### Styled Components
 
@@ -56,7 +43,7 @@ First, update to the latest version of Next.js: `npm install next@latest`. Then,
 // next.config.js
 
 module.exports = {
-  experimental: {
+  compiler: {
     // ssr and displayName are configured by default
     styledComponents: true,
   },
@@ -65,43 +52,14 @@ module.exports = {
 
 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)
-```
-
 ### Relay
 
 To enable [Relay](https://relay.dev/) support:
 
 ```js
 // next.config.js
 module.exports = {
-  experimental: {
+  compiler: {
     relay: {
       // This should match relay.config.js
       src: './',
@@ -123,7 +81,7 @@ To remove properties matching the default regex `^data-test`:
 ```js
 // next.config.js
 module.exports = {
-  experimental: {
+  compiler: {
     reactRemoveProperties: true,
   },
 }
@@ -134,30 +92,14 @@ To remove custom properties:
 ```js
 // next.config.js
 module.exports = {
-  experimental: {
+  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$'] },
   },
 }
 ```
 
-### 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
-  }
-}
-```
-
 ### Remove Console
 
 This transform allows for removing all `console.*` calls in application code (not `node_modules`). Similar to `babel-plugin-transform-remove-console`.
@@ -167,7 +109,7 @@ Remove all `console.*` calls:
 ```js
 // next.config.js
 module.exports = {
-  experimental: {
+  compiler: {
     removeConsole: true,
   },
 }
@@ -178,14 +120,30 @@ Remove `console.*` output except `console.error`:
 ```js
 // next.config.js
 module.exports = {
-  experimental: {
+  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.
@@ -195,11 +153,56 @@ First, update to the latest version of Next.js: `npm install next@latest`. Then,
 ```js
 {
   "compilerOptions": {
-    "jsxImportSource": true
+    "jsxImportSource": 'preact'
   }
 }
 ```
 
+## 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).
+
+### 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)
+```
+
 ## 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.

errors/ignored-compiler-options.md

@@ -0,0 +1,9 @@
+# ignored-compiler-options
+
+#### Why This Error Occurred
+
+Options under the `compiler` key in `next.config.js` only apply to the new Rust based compiler and will be ignored if Babel is used instead. This message will appear if Next.js detects a Babel configuration file while `compiler` options are configured in `next.config.js`
+
+### Useful Links
+
+- [Next.js Compiler](https://nextjs.org/docs/advanced-features/compiler)