eslint-plugin-barrel-files

3.0.1 verified Sat Apr 25 auth: no javascript

ESLint plugin to detect barrel files (re-export aggregators) and imports from them, preventing unnecessary module loading in non-bundler environments. Current stable version 3.0.1. Release cadence is irregular; last major v3 dropped support for older ESLint versions. Differentiator: specifically targets barrel file patterns that cause performance issues in test runners, browsers, CDNs, and server-side runtimes where tree-shaking is absent. Alternatives like eslint-plugin-import have broader scope but don't focus on barrel files specifically.

Common errors

error ESLint couldn't find the plugin "eslint-plugin-barrel-files". ↓

cause Plugin not installed or ESLint cannot resolve it in flat config without import.

fix

Run 'npm install eslint-plugin-barrel-files --save-dev' and ensure you import it at the top of eslint.config.js: import plugin from 'eslint-plugin-barrel-files';

error Configuration for rule "barrel-files/avoid-barrel-files" is invalid: Expected an array or object. ↓

cause Incorrect rule configuration format; rule severity must be a string or number, not an object.

fix

Use 'barrel-files/avoid-barrel-files': 'error' or 'barrel-files/avoid-barrel-files': ['warn', { /* options */ }].

error Definition for rule 'avoid-barrel-files' was not found. ↓

cause Missing prefix 'barrel-files/' in rule name.

fix

Use 'barrel-files/avoid-barrel-files' instead of 'avoid-barrel-files'.

Warnings

breaking Version 3.x requires ESLint >=9 or ESLint >=5 but with flat config; legacy .eslintrc support may behave differently. ↓

fix Update to ESLint flat config (eslint.config.js) or continue using v2.x for .eslintrc support.

deprecated The 'avoid-namespace-import' rule is considered deprecated in favor of 'avoid-re-export-all' as it covers more cases. ↓

fix Use 'barrel-files/avoid-re-export-all' instead.

gotcha Plugin rules analyze only files included in ESLint's linting scope; files outside must be explicitly included via 'files' in flat config. ↓

fix In eslint.config.js, add 'files: ["**/*.js"]' to the config object that applies the barrel-files rules.

gotcha The plugin does not automatically detect barrel files in node_modules; you must configure ESLint to ignore node_modules or exclude them manually. ↓

fix Add 'ignorePatterns: ["node_modules"]' in your config.

Install

npm install eslint-plugin-barrel-files

yarn add eslint-plugin-barrel-files

pnpm add eslint-plugin-barrel-files

Imports

plugin
wrong
```
const { rules } = require('eslint-plugin-barrel-files');
```
correct
```
import plugin from 'eslint-plugin-barrel-files';
```
Default export is the plugin object; in ESLint flat config, use import plugin from 'eslint-plugin-barrel-files' and spread plugin.configs.recommended.

recommended config

wrong

module.exports = { plugins: ['barrel-files'], rules: { 'barrel-files/avoid-barrel-files': 'error' } };

correct

import plugin from 'eslint-plugin-barrel-files';
export default [
  ...plugin.configs.recommended
];

In ESLint flat config (>=9), use the recommended config exported by the plugin. For legacy .eslintrc, use plugins: ['barrel-files'].

avoid-barrel-files rule

wrong

{
  rules: {
    'avoid-barrel-files': 'error'
  }
}

correct

// flat config:
{
  rules: {
    'barrel-files/avoid-barrel-files': 'error'
  }
}

Rule names must be prefixed with 'barrel-files/' because the plugin is namespaced.

Quickstart

Shows how to configure eslint-plugin-barrel-files in ESLint flat config (recommended) and legacy .eslintrc format.

// eslint.config.js (flat config)
import plugin from 'eslint-plugin-barrel-files';

export default [
  {
    files: ['**/*.js', '**/*.ts'],
    ...plugin.configs.recommended,
  },
  // Or selectively enable rules:
  {
    files: ['**/*.js'],
    plugins: { 'barrel-files': plugin },
    rules: {
      'barrel-files/avoid-barrel-files': 'error',
      'barrel-files/avoid-importing-barrel-files': 'warn',
    }
  }
];

// .eslintrc legacy config:
// {
//   plugins: ['barrel-files'],
//   rules: {
//     'barrel-files/avoid-barrel-files': 'error',
//   }
// }

// Then run: npx eslint .