babel-plugin-import

Modular import plugin for babel, compatible with antd, antd-mobile, lodash, material-ui, and so on.

---

Why babel-plugin-import

• English Instruction
• 中文说明

Where to add babel-plugin-import

• babelrc
• babel-loader

Example

{ "libraryName": "antd" }

1import { Button } from 'antd';
2ReactDOM.render(<Button>xxxx</Button>);
3
4      ↓ ↓ ↓ ↓ ↓ ↓
5
6var _button = require('antd/lib/button');
7ReactDOM.render(<_button>xxxx</_button>);

{ "libraryName": "antd", style: "css" }

1import { Button } from 'antd';
2ReactDOM.render(<Button>xxxx</Button>);
3
4      ↓ ↓ ↓ ↓ ↓ ↓
5
6var _button = require('antd/lib/button');
7require('antd/lib/button/style/css');
8ReactDOM.render(<_button>xxxx</_button>);

{ "libraryName": "antd", style: true }

1import { Button } from 'antd';
2ReactDOM.render(<Button>xxxx</Button>);
3
4      ↓ ↓ ↓ ↓ ↓ ↓
5
6var _button = require('antd/lib/button');
7require('antd/lib/button/style');
8ReactDOM.render(<_button>xxxx</_button>);

Note : with style: true css source files are imported and optimizations can be done during compilation time. With style: "css", pre bundled css files are imported as they are.

style: true can reduce the bundle size significantly, depending on your usage of the library.

Usage

1npm install babel-plugin-import --save-dev

Via .babelrc or babel-loader.

1{
2  "plugins": [["import", options]]
3}

options

options can be object.

1{
2  "libraryName": "antd",
3  "style": true,   // or 'css'
4}

1{
2  "libraryName": "lodash",
3  "libraryDirectory": "",
4  "camel2DashComponentName": false,  // default: true
5}

1{
2  "libraryName": "@material-ui/core",
3  "libraryDirectory": "components",  // default: lib
4  "camel2DashComponentName": false,  // default: true
5}

options can be an array. It's not available in babel@7+

For Example:

1[
2  {
3    "libraryName": "antd",
4    "libraryDirectory": "lib",   // default: lib
5    "style": true
6  },
7  {
8    "libraryName": "antd-mobile"
9  },
10]

Options can't be an array in babel@7+, but you can add plugins with name to support multiple dependencies.

For Example:

1// .babelrc
2"plugins": [
3  ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],
4  ["import", { "libraryName": "antd-mobile", "libraryDirectory": "lib"}, "antd-mobile"]
5]

style

• ["import", { "libraryName": "antd" }]: import js modularly
• ["import", { "libraryName": "antd", "style": true }]: import js and css modularly (LESS/Sass source files)
• ["import", { "libraryName": "antd", "style": "css" }]: import js and css modularly (css built files)

If option style is a Function, babel-plugin-import will auto import the file which filepath equal to the function return value. This is useful for the components library developers.

e.g.

• ["import", { "libraryName": "antd", "style": (name) => `${name}/style/2x` }]: import js and css modularly & css file path is ComponentName/style/2x

If a component has no style, you can use the style function to return a false and the style will be ignored.

e.g.

1[
2  "import",
3    {
4      "libraryName": "antd",
5      "style": (name: string, file: Object) => {
6        if(name === 'antd/lib/utils'){
7          return false;
8        }
9        return `${name}/style/2x`;
10      }
11    }
12]

styleLibraryDirectory

• ["import", { "libraryName": "element-ui", "styleLibraryDirectory": "lib/theme-chalk" }]: import js and css modularly

If styleLibraryDirectory is provided (default null), it will be used to form style file path, style will be ignored then. e.g.

1{
2  "libraryName": "element-ui",
3  "styleLibraryDirectory": "lib/theme-chalk",
4}
5
6import { Button } from 'element-ui';
7
8      ↓ ↓ ↓ ↓ ↓ ↓
9
10var _button = require('element-ui/lib/button');
11require('element-ui/lib/theme-chalk/button');

customName

We can use customName to customize import file path.

For example, the default behavior:

1import { TimePicker } from "antd"
2↓ ↓ ↓ ↓ ↓ ↓
3var _button = require('antd/lib/time-picker');

You can set camel2DashComponentName to false to disable transfer from camel to dash:

1import { TimePicker } from "antd"
2↓ ↓ ↓ ↓ ↓ ↓
3var _button = require('antd/lib/TimePicker');

And finally, you can use customName to customize each name parsing:

1[
2  "import",
3    {
4      "libraryName": "antd",
5      "customName": (name: string, file: object) => {
6        const filename = file.opts.filename;
7        if (name === 'TimePicker'){
8          return 'antd/lib/custom-time-picker';
9        }
10        if (filename.indexOf('/path/to/my/different.js') >= 0) {
11          return 'antd/lib/custom-name';
12        }
13        return `antd/lib/${name}`;
14      }
15    }
16]

So this result is:

1import { TimePicker } from "antd"
2↓ ↓ ↓ ↓ ↓ ↓
3var _button = require('antd/lib/custom-time-picker');

In some cases, the transformer may serialize the configuration object. If we set the customName to a function, it will lost after the serialization.

So we also support specifying the customName with a JavaScript source file path:

1[
2  "import",
3    {
4      "libraryName": "antd",
5      "customName": require('path').resolve(__dirname, './customName.js')
6    }
7]

The customName.js looks like this:

1module.exports = function customName(name) {
2  return `antd/lib/${name}`;
3};

customStyleName

customStyleName works exactly the same as customName, except that it deals with style file path.

transformToDefaultImport

Set this option to false if your module does not have a default export.

Note

babel-plugin-import will not work properly if you add the library to the webpack config vendor.