SWC import modularization plugin (#34969)

Author: losfair

docs/advanced-features/compiler.md

@@ -233,6 +233,89 @@ module.exports = {
 
 If you have feedback about `swcMinify`, please share it on the [feedback discussion](https://github.com/vercel/next.js/discussions/30237).
 
+### Modularize Imports
+
+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.
+
+The config:
+
+```js
+// next.config.js
+module.exports = {
+  experimental: {
+    modularizeImports: {
+      'my-library/?(((\\w*)?/?)*)': {
+        transform: 'my-library/{{ matches.[1] }}/{{member}}',
+      },
+    },
+  },
+}
+```
+
+Cause this code:
+
+```js
+import { MyModule } from 'my-library'
+import { App } from 'my-library/components'
+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.
+
 ## 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.

examples/modularize-imports/.gitignore

@@ -0,0 +1,34 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel

examples/modularize-imports/README.md

@@ -0,0 +1,27 @@
+# Modularize Imports Example
+
+This example shows how to use the `modularizeImports` config option.
+
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/modularize-imports)
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/modularize-imports&project-name=modularize-imports&repository-name=modularize-imports)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
+
+```bash
+npx create-next-app --example modularize-imports modularize-imports-app
+# or
+yarn create next-app --example modularize-imports modularize-imports-app
+```
+
+Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).

examples/modularize-imports/components/halves/LeftHalf.js

@@ -0,0 +1,3 @@
+export default function LeftHalf() {
+  return <span>Modularize</span>
+}

examples/modularize-imports/components/halves/RightHalf.js

@@ -0,0 +1,3 @@
+export default function RightHalf() {
+  return <span>Imports</span>
+}

examples/modularize-imports/components/halves/index.js

@@ -0,0 +1,5 @@
+// import LeftHalf from './LeftHalf'
+// import RightHalf from './RightHalf'
+
+// Remove the exports here so that we can verify that `modularize-imports` is working.
+// export { LeftHalf, RightHalf };

examples/modularize-imports/next.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  experimental: {
+    modularizeImports: {
+      '../components/halves': {
+        transform: '../components/halves/{{ member }}',
+      },
+    },
+  },
+}

examples/modularize-imports/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "latest",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  }
+}

examples/modularize-imports/pages/index.js

@@ -0,0 +1,10 @@
+import { LeftHalf, RightHalf } from '../components/halves'
+
+const Index = () => (
+  <div>
+    <LeftHalf />
+    <RightHalf />
+  </div>
+)
+
+export default Index