babel-plugin-import

What is babel-plugin-import?

babel-plugin-import is a Babel plugin for modular import of components, enabling on-demand loading of specific parts of a library. This can help reduce bundle sizes by only including the necessary parts of a library in the final build.

What are babel-plugin-import's main functionalities?

Importing specific components

This feature allows you to import specific components from a library like 'antd' without importing the entire library. The configuration in babel.config.js specifies the library name, directory, and style options. The import statement in the JavaScript file then only includes the 'Button' component.

/* Babel configuration (babel.config.js) */
{
  "plugins": [
    [
      "import",
      {
        "libraryName": "antd",
        "libraryDirectory": "es",
        "style": "css"
      }
    ]
  ]
}

/* Usage in a JavaScript file */
import { Button } from 'antd';

Customizing import paths

This feature allows you to customize the import paths for libraries like 'lodash'. The configuration in babel.config.js specifies the library name and options like 'camel2DashComponentName' to control the import path format. The import statement in the JavaScript file then only includes the 'debounce' function.

/* Babel configuration (babel.config.js) */
{
  "plugins": [
    [
      "import",
      {
        "libraryName": "lodash",
        "libraryDirectory": "",
        "camel2DashComponentName": false
      },
      "lodash"
    ]
  ]
}

/* Usage in a JavaScript file */
import { debounce } from 'lodash';

Other packages similar to babel-plugin-import

babel-plugin-lodash

babel-plugin-lodash is a Babel plugin that cherry-picks Lodash modules so you don’t have to. It helps reduce the size of your Lodash imports by only including the specific functions you use. Compared to babel-plugin-import, it is more specialized for Lodash and offers more granular control over Lodash imports.

babel-plugin-transform-imports

babel-plugin-transform-imports is a Babel plugin that allows you to transform import statements for specific modules. It provides a flexible way to rewrite import paths and can be used with various libraries. Compared to babel-plugin-import, it offers more customization options for transforming imports but may require more configuration.

README

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" }

import { Button } from 'antd';
ReactDOM.render(<Button>xxxx</Button>);

      ↓ ↓ ↓ ↓ ↓ ↓

var _button = require('antd/lib/button');
ReactDOM.render(<_button>xxxx</_button>);

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

import { Button } from 'antd';
ReactDOM.render(<Button>xxxx</Button>);

      ↓ ↓ ↓ ↓ ↓ ↓

var _button = require('antd/lib/button');
require('antd/lib/button/style/css');
ReactDOM.render(<_button>xxxx</_button>);

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

import { Button } from 'antd';
ReactDOM.render(<Button>xxxx</Button>);

      ↓ ↓ ↓ ↓ ↓ ↓

var _button = require('antd/lib/button');
require('antd/lib/button/style');
ReactDOM.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

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

Via .babelrc or babel-loader.

{
  "plugins": [["import", options]]
}

options

options can be object.

{
  "libraryName": "antd",
  "style": true,   // or 'css'
}

{
  "libraryName": "lodash",
  "libraryDirectory": "",
  "camel2DashComponentName": false,  // default: true
}

{
  "libraryName": "@material-ui/core",
  "libraryDirectory": "components",  // default: lib
  "camel2DashComponentName": false,  // default: true
}

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

For Example:

[
  {
    "libraryName": "antd",
    "libraryDirectory": "lib",   // default: lib
    "style": true
  },
  {
    "libraryName": "antd-mobile"
  },
]

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

For Example:

// .babelrc
"plugins": [
  ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],
  ["import", { "libraryName": "antd-mobile", "libraryDirectory": "lib"}, "antd-mobile"]
]

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.

[
  "import",
    {
      "libraryName": "antd",
      "style": (name: string, file: Object) => {
        if(name === 'antd/lib/utils'){
          return false;
        }
        return `${name}/style/2x`;
      }
    }
]

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.

{
  "libraryName": "element-ui",
  "styleLibraryDirectory": "lib/theme-chalk",
}

import { Button } from 'element-ui';

      ↓ ↓ ↓ ↓ ↓ ↓

var _button = require('element-ui/lib/button');
require('element-ui/lib/theme-chalk/button');

customName

We can use customName to customize import file path.

For example, the default behavior:

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

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

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

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

[
  "import",
    {
      "libraryName": "antd",
      "customName": (name: string, file: object) => {
        const filename = file.opts.filename;
        if (name === 'TimePicker'){
          return 'antd/lib/custom-time-picker';
        }
        if (filename.indexOf('/path/to/my/different.js') >= 0) {
          return 'antd/lib/custom-name';
        }
        return `antd/lib/${name}`;
      }
    }
]

So this result is:

import { TimePicker } from "antd"
↓ ↓ ↓ ↓ ↓ ↓
var _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:

[
  "import",
    {
      "libraryName": "antd",
      "customName": require('path').resolve(__dirname, './customName.js')
    }
]

The customName.js looks like this:

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

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.