eslint-plugin-barrel-boundary

Enforce module boundaries via barrel files.

Why use this?

Stop "spaghetti imports" and enforce clean module boundaries!

Instead of reaching deep into the internal structure of a directory:

// ❌ Bad: Leaking internal implementation details
import { SmallConfirm } from "../popup/types/smallConfirm";
import { usePopup } from "../popup/context";

Enforce importing from the barrel file (index.ts) acting as the public API:

// ✅ Good: Clean module boundary
import { SmallConfirm, usePopup } from "../popup";

This plugin automatically detects if a directory has an index file and enforces usage of it, keeping your project structure clean and refactor-friendly.

Installation

You'll first need to install ESLint:

npm i eslint --save-dev

Next, install eslint-plugin-barrel-boundary:

npm install eslint-plugin-barrel-boundary --save-dev

Usage

Flat Config (ESLint v9.x)

In your eslint.config.js (or .mjs), import the plugin and use the recommended configuration.

import barrelBoundary from "eslint-plugin-barrel-boundary";

export default [
  // 1. Use the recommended configuration (this enables the plugin and the rule)
  barrelBoundary.configs["flat/recommended"],

  // 2. Custom Configuration (Optional)
  // You can override the rules in a subsequent object
  {
    rules: {
      "barrel-boundary/enforce-barrel-files": [
        "error",
        {
          detectAliases: true, // Support for path aliases (e.g., "@/components")
        },
      ],
    },
  },
];

Legacy Config (.eslintrc)

If you are still using the legacy configuration format (ESLint < 9 or .eslintrc files):

{
  "plugins": ["barrel-boundary"],
  "extends": ["plugin:barrel-boundary/recommended"],
  "rules": {
    // Optional: Override defaults
    "barrel-boundary/enforce-barrel-files": ["error", { "detectAliases": true }]
  }
}

Configurations

| | Name | | :-- | :----------------- | | | flat/recommended | | ✅ | recommended |

Rules

💼 Configurations enabled in.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.

| Name                 | Description | 💼 | 🔧 | | :--------------------------------------------------------- | :-------------------------------------------------------------- | :----------------------------- | :-- | | enforce-barrel-files | Disallow deep imports from directories that have an index file. | ✅ ![badge-flat/recommended][] | 🔧 |