eslint-plugin-module-boundaries

An ESLint plugin to enforce module boundaries by preventing imports from outside module directories.

Installation

npm install --save-dev eslint-plugin-module-boundaries

Usage

Add module-boundaries to the plugins section of your ESLint configuration:

{
    "plugins": [
        "module-boundaries"
    ]
}

Then configure the rules you want to use under the rules section:

{
    "rules": {
        "module-boundaries/no-cross-module-imports": ["error", {
            "moduleDirectories": [
                "src/modules/user",
                "src/modules/auth",
                "src/modules/payment"
            ],
            "aliases": {
                "@components": "src/modules/user/components",
                "@auth": "src/modules/auth",
                "@": "lib"
            }
        }]
    }
}

Rules

no-cross-module-imports

This rule prevents imports from outside the current module directory. It automatically detects and supports:

• ES Module syntax (import statements)
• CommonJS syntax (require() calls)
• Dynamic imports (import() expressions)

Examples of Invalid Imports

// File: src/modules/user/components/UserProfile.js
// Module: src/modules/user

import { login } from '../../auth/views/Login';  // Invalid
import { utils } from '@/utils';  // Invalid (alias resolves to lib/utils)

async function loadLogin() {
  const Player = await import('../../common/VideoPlayer');  // Invalid
}

const component = require('../../auth/views/Login');  // Invalid

Examples of Valid Imports

// File: src/modules/user/components/UserProfile.js
// Module: src/modules/user

/* Relative imports within the same module (allowed) */
import { something } from './local-file';
import { helper } from '../utils/helper';

/* External package dependencies (allowed) */
import lodash from 'lodash';

/* Aliased imports within the same module (allowed) */
import { Button } from '@components/Button';
  // alias resolves to src/modules/user/components/Button

/* Dynamic imports within the same module (allowed) */
async function loadButton() {
  const Button = await import('@components/Button');
  // alias resolves to src/modules/user/components/Button
}

Options

The rule accepts an object with the following properties:

• moduleDirectories (required): An array of directory paths that represent modules. These paths should be relative to your project root. Files within these directories should only be allowed to import from within their own module directory.
  • allow Directory paths should most commonly be a string, which locks down all imports from anywhere outside of this directory. However, if you need to allow some exceptions you can instead pass and object containing an "allow" property. allow should be an array of directory paths from which this module is explicitly ALLOWED to import.
    • Example: { "path": "src/modules/user", "allow":["lib/constants"] }
• aliases (optional): An object mapping import aliases to their actual paths. This is useful for projects using TypeScript or Babel with path aliases configured. Any prefix can be used for aliases (e.g., @, #, ~, etc.). The resolved paths must still respect module boundaries.
  • Note: If you do not configure aliases here, any imports that start with special characters like @ will be treated as namespaced external package imports and will pass validation.

Example configuration:

{
    "rules": {
        "module-boundaries/no-cross-module-imports": ["error", {
            "moduleDirectories": [
                "src/modules/user",
                "src/modules/auth",
                {
                    "path": "src/modules/payment",
                    "allow": {
                        "path": "src/modules/user",
                        "allow":["lib/constants"],
                    },
                },
            ],
            "aliases": {
                "@components": "src/modules/user/components",
                "@auth": "src/modules/auth",
                "@": "lib"
            }
        }]
    }
}

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

License

MIT