babel-plugin-import

1.13.8 verified Sat Apr 25 auth: no javascript

A Babel plugin that transforms modular imports (e.g., import { Button } from 'antd') into individual require/import calls for only the used components and their styles, reducing bundle size. Version 1.13.8 is the latest stable release, maintained by the Ant Design team. It supports customizable library names, directories, style imports (including CSS, SASS/LESS, or none), and camelCase-to-kebab-case conversion. Key differentiators: works with antd, antd-mobile, lodash, material-ui, and many other libraries; supports styleLibraryDirectory for custom style layouts; and is widely adopted in the React ecosystem for on-demand loading without tree-shaking.

Common errors

error Error: [BABEL] unknown: You gave us a visitor for the node type "Program" but it's not a valid type (While processing: ...) ↓

cause Using an array of options in Babel 7+ like plugins: [['import', [{...}, {...}]]]

fix

Either use separate plugin entries or pass a single options object. For multiple libraries: [['import', {libraryName:'antd'}, 'antd'], ['import', {libraryName:'antd-mobile'}, 'antd-mobile']]

error Error: Cannot find module 'babel-plugin-import' ↓

cause babel-plugin-import is not installed or not in node_modules.

fix

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

error Module not found: Error: Can't resolve 'antd/lib/button/style' ↓

cause The specified style path does not exist; often because libraryName is incorrect or style option is misconfigured.

fix

Verify the library name and style path. For antd, use libraryName: 'antd' and style: 'css' for built CSS, or style: true for LESS source.

error Transform error: Cannot read property 'someMethod' of undefined at ... (related to babel-plugin-import) ↓

cause The plugin tries to traverse an AST node that is not supported, often due to an incompatible Babel version.

fix

Update babel-plugin-import to the latest version (1.13.8) and ensure @babel/core is >=7.0.0.

Warnings

breaking babel-plugin-import does not work with Babel 7+ when using array of options; use separate plugin entries instead. ↓

fix Instead of [ {"libraryName":"antd"}, {"libraryName":"antd-mobile"} ], define two plugin entries with unique names: [['import',{libraryName:'antd'},'antd'], ['import',{libraryName:'antd-mobile'},'antd-mobile']]

deprecated Setting style: 'css' imports pre-built CSS files; prefer style: true to import LESS source files for smaller bundle. ↓

fix Use style: true to import LESS/Sass source files and allow tree-shaking of styles.

gotcha Plugin does not transform direct imports like import Button from 'antd/lib/button'; it only transforms import { Button } from 'antd'. ↓

fix Always use named imports from the library root (e.g., import { Button } from 'antd') to allow the plugin to work.

breaking In Babel 7+, the plugin name must be unique when using multiple instances; otherwise, the second instance overrides the first. ↓

fix Add a third string argument to each plugin entry for uniqueness, e.g., ['import', {...}, 'antd'].

gotcha The plugin transforms only import statements, not require() calls (e.g., const Button = require('antd').Button). ↓

fix Use ES module imports (import ... from 'antd') instead of CommonJS require.

Install

npm install babel-plugin-import

yarn add babel-plugin-import

pnpm add babel-plugin-import

Imports

default (plugin)

wrong

const plugin = require('babel-plugin-import') // no named export

correct

module.exports = { plugins: [['import', options]] }

Used as a Babel plugin in .babelrc or babel.config.js. No direct JavaScript import.

import { Button } from 'antd'
wrong
```
import Button from 'antd/lib/button'; // defeats purpose of plugin
```
correct
```
import { Button } from 'antd'; // transformed to individual imports
```
Plugin automatically transforms named imports from the library to individual module imports. No explicit call needed.

configure via .babelrc

wrong

{
  "plugins": ["import", { "libraryName": "antd" }] // missing nested array

correct

{
  "plugins": [["import", { "libraryName": "antd", "style": "css" }]]
}

Options must be passed as second element of an array within the plugins array.

Quickstart

Configures babel-plugin-import for antd with CSS style imports, showing the transformation of a component import.

// .babelrc or babel.config.js
module.exports = {
  plugins: [
    ['import', {
      libraryName: 'antd',
      style: 'css', // or true for LESS source
    }],
  ],
};

// Your React component
import { Button, DatePicker } from 'antd';
// Transforms to:
// var _button = require('antd/lib/button');
// require('antd/lib/button/style/css');
// var _datePicker = require('antd/lib/date-picker');
// require('antd/lib/date-picker/style/css');

const App = () => (
  <div>
    <Button>Click me</Button>
    <DatePicker />
  </div>
);