babel-plugin-transform-barrels

1.0.23 verified Sat Apr 25 auth: no javascript

A Babel plugin that transforms indirect imports through barrel files (index.js) into direct imports. Current stable version is 1.0.23. The plugin supports Webpack, Vite, and Jest, resolving imports to improve bundling performance and avoid circular dependencies. Key differentiators include support for package.json exports field, jest.mock/requireActual, Webpack aliases, and caching. It is designed to be used as a Babel plugin with minimal configuration, offering options like alias, extensions, modulesDirs, and moduleIgnorePatterns. Version 1.0.23 adds moduleIgnorePatterns and fixes jest.mock bugs.

Common errors

error Error: [BABEL] unknown: The 'executorName' option is required. ↓

cause Missing executorName option in plugin configuration.

fix

Add executorName: 'webpack' (or 'jest' or 'vite') to the plugin options.

error Error: Module not found: Can't resolve './components' in '/path/to/src' ↓

cause The barrel file (index.js) does not exist or the import path is incorrect.

fix

Create an index.js file in the components folder that re-exports the desired modules, or correct the import path.

error Error: [BABEL] unknown: The 'alias' option should be an object. ↓

cause Passed a non-object value for alias (e.g., string or array).

fix

Ensure alias is an object with string keys and values, e.g., { '@': './src' }.

error Error: Cannot find module 'babel-plugin-transform-barrels' ↓

cause The package is not installed or not in node_modules.

fix

Run npm install --save-dev babel-plugin-transform-barrels.

Warnings

breaking In v1.0.16, the options 'webpackAlias' and 'jestAlias' were replaced by a single 'alias' option. Similarly, 'webpackExtensions' and 'jestExtensions' were replaced by 'extensions'. ↓

fix Update your config to use 'alias' and 'extensions' instead of the old option names.

breaking The 'babel-plugin-transform-barrels' plugin name must be used in babel config; using 'transform-barrels' without the 'babel-plugin-' prefix may not work in some setups. ↓

fix Use 'babel-plugin-transform-barrels' as the plugin name in your babel config.

gotcha The plugin only transforms imports that go through a barrel file (index.js). If your import is already direct, it is not modified. ↓

fix Ensure you have barrel files (index.js) that re-export modules, and that imports point to the barrel directory.

gotcha Jest mock calls: jest.mock('./components') will be transformed to jest.mock('./components/Button/Button') only if executorName is 'jest'. Without correct executorName, transformation may not work. ↓

fix Set executorName to 'jest' when using Jest.

gotcha The plugin uses caching (file-based) when isCacheEnabled is true. Cache may cause stale transformations if barrel files change without version increment. ↓

fix Clear cache manually (e.g., delete the .cache folder) or disable caching during development.

Install

npm install babel-plugin-transform-barrels

yarn add babel-plugin-transform-barrels

pnpm add babel-plugin-transform-barrels

Imports

default (plugin)

wrong

import plugin from 'babel-plugin-transform-barrels'; // Not meant for consumer code

correct

module.exports = require('babel-plugin-transform-barrels');
// or in babel config: plugins: [['babel-plugin-transform-barrels', { executorName: 'webpack' }]]

This is a Babel plugin, not a library to import in application code. It is added to babel config as a string name.

babelTransform

wrong

import { babelTransform } from 'babel-plugin-transform-barrels';

correct

const babelTransform = require('./config/jest/babelTransform');

The babelTransform.js file is provided in the package's config folder and should be copied to your project.

Options

wrong

// Using wrong executorName like 'webpack' for Jest, or omitting executorName

correct

// In babel.config.js:
module.exports = { plugins: [['babel-plugin-transform-barrels', { executorName: 'jest', alias: { '@': './src' } }]] };

Options are passed as the second element of the plugin array. executorName is required for proper behavior.

Quickstart

Shows installation, basic configuration with all options, and an example import transformation.

// 1. Install
// npm install --save-dev babel-plugin-transform-barrels

// 2. babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-transform-barrels', {
      executorName: 'webpack', // or 'jest' or 'vite'
      alias: { '@': './src' },
      extensions: ['.js', '.jsx', '.ts', '.tsx'],
      modulesDirs: ['node_modules'],
      moduleIgnorePatterns: [],
      isCacheEnabled: false
    }]
  ]
};

// 3. Before: import { Button, List } from './components';
// After: import { Button } from './components/Button/Button';
//         import { List } from './components/List/List';