Unverified Commit c5453453 authored by Shu Uesugi's avatar Shu Uesugi Committed by GitHub

Improve modularized imports docs and add config options to example (#44560)

This PR improves the [Modularize Imports](https://nextjs.org/docs/advanced-features/compiler#modularize-imports) section of Next.js Compiler docs as well as [the `modularize-imports` example](https://github.com/vercel/next.js/tree/canary/examples/modularize-imports). They were originally added in [this PR](https://github.com/vercel/next.js/pull/34969).

- Link to [the `modularize-imports` example](https://github.com/vercel/next.js/tree/canary/examples/modularize-imports) was missing from the docs.
- Clarified some explanations and reorganized the content so it's easier to understand.
- Added docs for `skipDefaultConversion`.
- Added docs for `preventFullImport`.
- Illustrated how to use `kebabCase` and `skipDefaultConversion` on the [the `modularize-imports` example](https://github.com/vercel/next.js/tree/canary/examples/modularize-imports).

## Documentation / Examples

- [x] Make sure the linting passes by running `pnpm build && pnpm lint`
- [x] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
parent ca73cbf6
...@@ -279,20 +279,27 @@ module.exports = { ...@@ -279,20 +279,27 @@ module.exports = {
### Modularize Imports ### Modularize Imports
<details open>
<summary><b>Examples</b></summary>
<ul>
<li><a href="https://github.com/vercel/next.js/blob/canary/examples/modularize-imports/">modularize-imports</a></li>
</ul>
</details>
Allows to modularize imports, similar to [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports). Allows to modularize imports, similar to [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports).
Transforms member style imports: Transforms member style imports of packages that use a “barrel file” (a single file that re-exports other modules):
```js ```js
import { Row, Grid as MyGrid } from 'react-bootstrap' import { Row, Grid as MyGrid } from 'react-bootstrap'
import { merge } from 'lodash' import { merge } from 'lodash'
``` ```
...into default style imports: ...into default style imports of each module. This prevents compilation of unused modules:
```js ```js
import Row from 'react-bootstrap/lib/Row' import Row from 'react-bootstrap/Row'
import MyGrid from 'react-bootstrap/lib/Grid' import MyGrid from 'react-bootstrap/Grid'
import merge from 'lodash/merge' import merge from 'lodash/merge'
``` ```
...@@ -303,7 +310,7 @@ Config for the above transform: ...@@ -303,7 +310,7 @@ Config for the above transform:
module.exports = { module.exports = {
modularizeImports: { modularizeImports: {
'react-bootstrap': { 'react-bootstrap': {
transform: 'react-bootstrap/lib/{{member}}', transform: 'react-bootstrap/{{member}}',
}, },
lodash: { lodash: {
transform: 'lodash/{{member}}', transform: 'lodash/{{member}}',
...@@ -312,13 +319,36 @@ module.exports = { ...@@ -312,13 +319,36 @@ module.exports = {
} }
``` ```
Advanced transformations: #### Handlebars variables and helper functions
- Using regular expressions 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:
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. 1. `member`: Has type `string`. The name of the member import.
2. `lowerCase`, `upperCase`, `camelCase`, `kebabCase`: Helper functions to convert a string to lower, upper, camel or kebab cases.
3. `matches`: Has type `string[]`. All groups matched by the regular expression. `matches.[0]` is the full match.
The config: For example, you can use the `kebabCase` helper like this:
```js
// next.config.js
module.exports = {
'my-library': {
transform: 'my-library/{{ kebabCase member }}',
},
}
```
The above config will transform your code as follows:
```js
// Before
import { MyModule } from 'my-library'
// After (`MyModule` was converted to `my-module`)
import MyModule from 'my-library/my-module'
```
You can also use regular expressions using Rust [regex](https://docs.rs/regex/latest/regex/) crate’s syntax:
```js ```js
// next.config.js // next.config.js
...@@ -331,30 +361,77 @@ module.exports = { ...@@ -331,30 +361,77 @@ module.exports = {
} }
``` ```
Cause this code: The above config will transform your code as follows:
```js ```js
// Before
import { MyModule } from 'my-library' import { MyModule } from 'my-library'
import { App } from 'my-library/components' import { App } from 'my-library/components'
import { Header, Footer } from 'my-library/components/App' import { Header, Footer } from 'my-library/components/App'
```
To become:
```js // After
import MyModule from 'my-library/MyModule' import MyModule from 'my-library/MyModule'
import App from 'my-library/components/App' import App from 'my-library/components/App'
import Header from 'my-library/components/App/Header' import Header from 'my-library/components/App/Header'
import Footer from 'my-library/components/App/Footer' import Footer from 'my-library/components/App/Footer'
``` ```
- Handlebars templating #### Using named imports
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: By default, `modularizeImports` assumes that each module uses default exports. However, this may not always be the case — named exports may be used.
```js
// my-library/MyModule.ts
// Using named export instead of default export
export const MyModule = {}
// my-library/index.ts
// The “barrel file” that re-exports `MyModule`
export { MyModule } from './MyModule'
```
In this case, you can use the `skipDefaultConversion` option to use named imports instead of default imports:
1. `matches`: Has type `string[]`. All groups matched by the regular expression. `matches.[0]` is the full match. ```js
2. `member`: Has type `string`. The name of the member import. // next.config.js
3. `lowerCase`, `upperCase`, `camelCase`, `kebabCase`: Helper functions to convert a string to lower, upper, camel or kebab cases. module.exports = {
'my-library': {
transform: 'my-library/{{member}}',
skipDefaultConversion: true,
},
}
```
The above config will transform your code as follows:
```js
// Before
import { MyModule } from 'my-library'
// After (imports `MyModule` using named import)
import { MyModule } from 'my-library/MyModule'
```
#### Preventing full import
If you use the `preventFullImport` option, the compiler will throw an error if you import a “barrel file” using default import. If you use the following config:
```js
// next.config.js
module.exports = {
lodash: {
transform: 'lodash/{{member}}',
preventFullImport: true,
},
}
```
The compiler will throw an error if you try to import the full `lodash` library (instead of using named imports):
```js
// Compiler error
import lodash from 'lodash'
```
## Experimental Features ## Experimental Features
......
...@@ -100,7 +100,7 @@ Each file inside your `pages/` directory will automatically be code split into i ...@@ -100,7 +100,7 @@ Each file inside your `pages/` directory will automatically be code split into i
<details open> <details open>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="https://github.com/Logflare/next-pino-logflare-logging-example">with-logging</a></li> <li><a href="https://github.com/Logflare/next-pino-logflare-logging-example">Pino and Logflare Example</a></li>
</ul> </ul>
</details> </details>
......
# Modularize Imports Example # Modularize Imports Example
This example shows how to use the `modularizeImports` config option. This example shows how to use the [`modularizeImports` config option](https://nextjs.org/docs/advanced-features/compiler#modularize-imports).
## Preview ## Preview
......
export function HeadingLarge({ children }: { children: React.ReactNode }) {
return <h1>{children}</h1>
}
// import HeadingLarge from './heading-large'
// Remove the exports here so that we can verify that `modularize-imports` is working.
// export { HeadingLarge };
// Flag as module for TypeScript
export {}
...@@ -8,6 +8,13 @@ const nextConfig = { ...@@ -8,6 +8,13 @@ const nextConfig = {
'../components/halves': { '../components/halves': {
transform: '../components/halves/{{ member }}', transform: '../components/halves/{{ member }}',
}, },
'../components/ui': {
// Use `kebabCase` helper to convert `HeadingLarge` to `heading-large`
transform: '../components/ui/{{ kebabCase member }}',
// Use `skipDefaultConversion`, since `HeadingLarge` is exported
// using named exports instead of default exports
skipDefaultConversion: true,
},
}, },
} }
......
// @ts-ignore // @ts-ignore
import { LeftHalf, RightHalf } from '../components/halves' import { LeftHalf, RightHalf } from '../components/halves'
// @ts-ignore
import { HeadingLarge } from '../components/ui'
export default function Index() { export default function Index() {
return ( return (
<div> <HeadingLarge>
<LeftHalf /> <LeftHalf />
<RightHalf /> <RightHalf />
</div> </HeadingLarge>
) )
} }
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment