1 | # babel-plugin-import
|
2 |
|
3 | Modular import plugin for babel, compatible with [antd](https://github.com/ant-design/ant-design), [antd-mobile](https://github.com/ant-design/ant-design-mobile), lodash, [material-ui](http://material-ui.com/), and so on.
|
4 |
|
5 | [![NPM version](https://img.shields.io/npm/v/babel-plugin-import.svg?style=flat)](https://npmjs.org/package/babel-plugin-import)
|
6 | [![Build Status](https://img.shields.io/travis/ant-design/babel-plugin-import.svg?style=flat)](https://travis-ci.org/ant-design/babel-plugin-import)
|
7 |
|
8 | ----
|
9 |
|
10 | ## Why babel-plugin-import
|
11 |
|
12 | - [English Instruction](https://ant.design/docs/react/getting-started#Import-on-Demand)
|
13 | - [中文说明](https://ant.design/docs/react/getting-started-cn#%E6%8C%89%E9%9C%80%E5%8A%A0%E8%BD%BD)
|
14 |
|
15 | ## Where to add babel-plugin-import
|
16 |
|
17 | - [babelrc](https://babeljs.io/docs/usage/babelrc/)
|
18 | - [babel-loader](https://github.com/babel/babel-loader)
|
19 |
|
20 | ## Example
|
21 |
|
22 | #### `{ "libraryName": "antd" }`
|
23 |
|
24 | ```javascript
|
25 | import { Button } from 'antd';
|
26 | ReactDOM.render(<Button>xxxx</Button>);
|
27 |
|
28 | ↓ ↓ ↓ ↓ ↓ ↓
|
29 |
|
30 | var _button = require('antd/lib/button');
|
31 | ReactDOM.render(<_button>xxxx</_button>);
|
32 | ```
|
33 |
|
34 | #### `{ "libraryName": "antd", style: "css" }`
|
35 |
|
36 | ```javascript
|
37 | import { Button } from 'antd';
|
38 | ReactDOM.render(<Button>xxxx</Button>);
|
39 |
|
40 | ↓ ↓ ↓ ↓ ↓ ↓
|
41 |
|
42 | var _button = require('antd/lib/button');
|
43 | require('antd/lib/button/style/css');
|
44 | ReactDOM.render(<_button>xxxx</_button>);
|
45 | ```
|
46 |
|
47 | #### `{ "libraryName": "antd", style: true }`
|
48 |
|
49 | ```javascript
|
50 | import { Button } from 'antd';
|
51 | ReactDOM.render(<Button>xxxx</Button>);
|
52 |
|
53 | ↓ ↓ ↓ ↓ ↓ ↓
|
54 |
|
55 | var _button = require('antd/lib/button');
|
56 | require('antd/lib/button/style');
|
57 | ReactDOM.render(<_button>xxxx</_button>);
|
58 | ```
|
59 |
|
60 | 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.
|
61 |
|
62 | `style: true` can reduce the bundle size significantly, depending on your usage of the library.
|
63 |
|
64 | ## Usage
|
65 |
|
66 | ```bash
|
67 | npm install babel-plugin-import --save-dev
|
68 | ```
|
69 |
|
70 | Via `.babelrc` or babel-loader.
|
71 |
|
72 | ```js
|
73 | {
|
74 | "plugins": [["import", options]]
|
75 | }
|
76 | ```
|
77 |
|
78 | ### options
|
79 |
|
80 | `options` can be object.
|
81 |
|
82 | ```javascript
|
83 | {
|
84 | "libraryName": "antd",
|
85 | "style": true, // or 'css'
|
86 | }
|
87 | ```
|
88 |
|
89 | ```javascript
|
90 | {
|
91 | "libraryName": "lodash",
|
92 | "libraryDirectory": "",
|
93 | "camel2DashComponentName": false, // default: true
|
94 | }
|
95 | ```
|
96 |
|
97 | ```javascript
|
98 | {
|
99 | "libraryName": "@material-ui/core",
|
100 | "libraryDirectory": "components", // default: lib
|
101 | "camel2DashComponentName": false, // default: true
|
102 | }
|
103 | ```
|
104 |
|
105 | ~`options` can be an array.~ It's not available in babel@7+
|
106 |
|
107 | For Example:
|
108 |
|
109 | ```javascript
|
110 | [
|
111 | {
|
112 | "libraryName": "antd",
|
113 | "libraryDirectory": "lib", // default: lib
|
114 | "style": true
|
115 | },
|
116 | {
|
117 | "libraryName": "antd-mobile"
|
118 | },
|
119 | ]
|
120 | ```
|
121 | `Options` can't be an array in babel@7+, but you can add plugins with name to support multiple dependencies.
|
122 |
|
123 | For Example:
|
124 |
|
125 | ```javascrit
|
126 | // .babelrc
|
127 | "plugins": [
|
128 | ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],
|
129 | ["import", { "libraryName": "antd-mobile", "libraryDirectory": "lib"}, "antd-mobile"]
|
130 | ]
|
131 | ```
|
132 |
|
133 | #### style
|
134 |
|
135 | - `["import", { "libraryName": "antd" }]`: import js modularly
|
136 | - `["import", { "libraryName": "antd", "style": true }]`: import js and css modularly (LESS/Sass source files)
|
137 | - `["import", { "libraryName": "antd", "style": "css" }]`: import js and css modularly (css built files)
|
138 |
|
139 | 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.
|
140 |
|
141 | e.g.
|
142 | - ``["import", { "libraryName": "antd", "style": (name) => `${name}/style/2x` }]``: import js and css modularly & css file path is `ComponentName/style/2x`
|
143 |
|
144 | If a component has no style, you can use the `style` function to return a `false` and the style will be ignored.
|
145 |
|
146 | e.g.
|
147 | ```js
|
148 | [
|
149 | "import",
|
150 | {
|
151 | "libraryName": "antd",
|
152 | "style": (name: string, file: Object) => {
|
153 | if(name === 'antd/lib/utils'){
|
154 | return false;
|
155 | }
|
156 | return `${name}/style/2x`;
|
157 | }
|
158 | }
|
159 | ]
|
160 | ```
|
161 |
|
162 | #### styleLibraryDirectory
|
163 |
|
164 | - `["import", { "libraryName": "element-ui", "styleLibraryDirectory": "lib/theme-chalk" }]`: import js and css modularly
|
165 |
|
166 | If `styleLibraryDirectory` is provided (default `null`), it will be used to form style file path,
|
167 | `style` will be ignored then. e.g.
|
168 |
|
169 | ```javascript
|
170 | {
|
171 | "libraryName": "element-ui",
|
172 | "styleLibraryDirectory": "lib/theme-chalk",
|
173 | }
|
174 |
|
175 | import { Button } from 'element-ui';
|
176 |
|
177 | ↓ ↓ ↓ ↓ ↓ ↓
|
178 |
|
179 | var _button = require('element-ui/lib/button');
|
180 | require('element-ui/lib/theme-chalk/button');
|
181 | ```
|
182 |
|
183 | #### customName
|
184 |
|
185 | We can use `customName` to customize import file path.
|
186 |
|
187 | For example, the default behavior:
|
188 |
|
189 | ```typescript
|
190 | import { TimePicker } from "antd"
|
191 | ↓ ↓ ↓ ↓ ↓ ↓
|
192 | var _button = require('antd/lib/time-picker');
|
193 | ```
|
194 |
|
195 | You can set `camel2DashComponentName` to `false` to disable transfer from camel to dash:
|
196 |
|
197 | ```typescript
|
198 | import { TimePicker } from "antd"
|
199 | ↓ ↓ ↓ ↓ ↓ ↓
|
200 | var _button = require('antd/lib/TimePicker');
|
201 | ```
|
202 |
|
203 | And finally, you can use `customName` to customize each name parsing:
|
204 |
|
205 | ```js
|
206 | [
|
207 | "import",
|
208 | {
|
209 | "libraryName": "antd",
|
210 | "customName": (name: string, file: object) => {
|
211 | const filename = file.opts.filename;
|
212 | if (name === 'TimePicker'){
|
213 | return 'antd/lib/custom-time-picker';
|
214 | }
|
215 | if (filename.indexOf('/path/to/my/different.js') >= 0) {
|
216 | return 'antd/lib/custom-name';
|
217 | }
|
218 | return `antd/lib/${name}`;
|
219 | }
|
220 | }
|
221 | ]
|
222 | ```
|
223 |
|
224 | So this result is:
|
225 |
|
226 | ```typescript
|
227 | import { TimePicker } from "antd"
|
228 | ↓ ↓ ↓ ↓ ↓ ↓
|
229 | var _button = require('antd/lib/custom-time-picker');
|
230 | ```
|
231 |
|
232 | In some cases, the transformer may serialize the configuration object. If we set the `customName` to a function, it will lost after the serialization.
|
233 |
|
234 | So we also support specifying the customName with a JavaScript source file path:
|
235 |
|
236 | ```js
|
237 | [
|
238 | "import",
|
239 | {
|
240 | "libraryName": "antd",
|
241 | "customName": require('path').resolve(__dirname, './customName.js')
|
242 | }
|
243 | ]
|
244 | ```
|
245 |
|
246 | The `customName.js` looks like this:
|
247 |
|
248 | ```js
|
249 | module.exports = function customName(name) {
|
250 | return `antd/lib/${name}`;
|
251 | };
|
252 | ```
|
253 |
|
254 | #### customStyleName
|
255 |
|
256 | `customStyleName` works exactly the same as customName, except that it deals with style file path.
|
257 |
|
258 | #### transformToDefaultImport
|
259 |
|
260 | Set this option to `false` if your module does not have a `default` export.
|
261 |
|
262 | ### Note
|
263 |
|
264 | babel-plugin-import will not work properly if you add the library to the webpack config [vendor](https://webpack.js.org/concepts/entry-points/#separate-app-and-vendor-entries).
|