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 = {
### 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).
Transforms member style imports:
Transforms member style imports of packages that use a “barrel file” (a single file that re-exports other modules):
```js
import { Row, Grid as MyGrid } from 'react-bootstrap'
import { merge } from 'lodash'
```
...into default style imports:
...into default style imports of each module. This prevents compilation of unused modules:
```js
import Row from 'react-bootstrap/lib/Row'
import MyGrid from 'react-bootstrap/lib/Grid'
import Row from 'react-bootstrap/Row'
import MyGrid from 'react-bootstrap/Grid'
import merge from 'lodash/merge'
```
......@@ -303,7 +310,7 @@ Config for the above transform:
module.exports = {
modularizeImports: {
'react-bootstrap': {
transform: 'react-bootstrap/lib/{{member}}',
transform: 'react-bootstrap/{{member}}',
},
lodash: {
transform: 'lodash/{{member}}',
......@@ -312,13 +319,36 @@ module.exports = {
}
```
Advanced transformations:
#### Handlebars variables and helper functions
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. `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.
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:
- Using regular expressions
```js
// Before
import { MyModule } from 'my-library'
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.
// After (`MyModule` was converted to `my-module`)
import MyModule from 'my-library/my-module'
```
The config:
You can also use regular expressions using Rust [regex](https://docs.rs/regex/latest/regex/) crate’s syntax:
```js
// next.config.js
......@@ -331,30 +361,77 @@ module.exports = {
}
```
Cause this code:
The above config will transform your code as follows:
```js
// Before
import { MyModule } from 'my-library'
import { App } from 'my-library/components'
import { Header, Footer } from 'my-library/components/App'
```
To become:
```js
// After
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
#### 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'
```
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`, `kebabCase`: Helper functions to convert a string to lower, upper, camel or kebab cases.
In this case, you can use the `skipDefaultConversion` option to use named imports instead of default imports:
```js
// next.config.js
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
......
......@@ -100,7 +100,7 @@ Each file inside your `pages/` directory will automatically be code split into i
<details open>
<summary><b>Examples</b></summary>
<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>
</details>
......
# 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
......
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 = {
'../components/halves': {
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
import { LeftHalf, RightHalf } from '../components/halves'
// @ts-ignore
import { HeadingLarge } from '../components/ui'
export default function Index() {
return (
<div>
<HeadingLarge>
<LeftHalf />
<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