meijer.works

eslint-plugin-internal-boundaries

github npm

ESLint plugin that enforces internal module boundaries: do not import from another module’s internal/.

Install

npm install -D eslint-plugin-internal-boundaries

Usage

Add the plugin (without the eslint-plugin- prefix) and enable the single rule:

// .eslintrc.js (or .cjs/.json)
module.exports = {
  plugins: ['internal-boundaries'],
  rules: {
    'internal-boundaries/no-outside-imports': 'error',
  },
};

Rule: internal-boundaries/no-outside-imports

  • Blocks importing from any path that contains /internal/ unless the importer lives under the same directory tree root.
  • Works with CommonJS require(), static imports, and dynamic import() with string literals.
  • Resolution is delegated to eslint-plugin-import resolvers configured via import/resolver settings.

Examples

Given a project structure:

./app
├── module-a
│   ├── internal
│   │   ├── helper-a.ts
│   │   └── config-a.ts
│   └── service-a.ts
├── module-b
│   ├── internal
│   │   └── helper-b.ts
│   └── service-b.ts
└── common
    └── utils.ts

Valid (allowed):

  • app/module-a/service-a.ts → ./internal/helper-a.ts
  • app/module-b/service-b.ts → ./internal/helper-b.ts

Invalid (blocked):

  • app/module-a/service-a.ts → ../module-b/internal/helper-b.ts
  • app/common/utils.ts → ../module-a/internal/helper-a.ts

How it determines the boundary

If an import path resolves to something that includes /internal/, the rule finds the path root up to, but not including, internal/ and only allows imports from files whose absolute path starts with that same root.

Aliases

If you use path aliases (for example via tsconfig paths), they will be resolved before applying the boundary check. That means these are considered equivalent and enforced correctly:

  • #alias/module-a/internal/helper-a
  • ~/app/module-a/internal/helper-a

Resolvers

This rule resolves imports using the same mechanism as eslint-plugin-import, via eslint-module-utils/resolve. Configure resolvers in ESLint settings and install the resolver packages you reference.

Legacy config example:

// .eslintrc.js (or .cjs/.json)
module.exports = {
  plugins: ['internal-boundaries'],
  settings: {
    'import/resolver': {
      // You must install these in your project:
      //   npm i -D eslint-import-resolver-typescript eslint-import-resolver-node
      typescript: true,
      node: true,
    },
  },
  rules: {
    'internal-boundaries/no-outside-imports': 'error',
  },
};

ESLint v9 flat config example:

// eslint.config.js
import tseslint from 'typescript-eslint';
import internalBoundaries from 'eslint-plugin-internal-boundaries';

export default [
  ...tseslint.configs.recommended, // sets @typescript-eslint/parser for .ts/.tsx
  {
    plugins: { 'internal-boundaries': internalBoundaries },
    settings: { 'import/resolver': { typescript: true, node: true } },
    rules: { 'internal-boundaries/no-outside-imports': 'error' },
  },
];

Notes:

  • Install the resolver packages you configure: eslint-import-resolver-typescript (for TS path aliases, etc.) and eslint-import-resolver-node (for Node-style resolution), if you use them.
  • This plugin bundles the call to eslint-module-utils/resolve; you don’t need to install eslint-module-utils separately.

TypeScript parser

If you lint .ts/.tsx files, ESLint needs @typescript-eslint/parser to parse them. The resolver is independent of parsing, but the rule still needs a valid AST.

Quick example (legacy config):

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['internal-boundaries'],
  settings: { 'import/resolver': { typescript: true, node: true } },
  rules: { 'internal-boundaries/no-outside-imports': 'error' },
};

Debugging

You can inspect decisions by enabling the debug logger:

DEBUG=internal-boundaries eslint .

Why enforce internal boundaries?

  • Encourages encapsulation and modular design.
  • Makes refactors safer by preventing cross-module coupling on internals.
  • Keeps architectural boundaries clear and intentional.

Background

This rule is inspired by Go’s “internal” packages design. In Go, any code placed under an internal/ directory can only be imported by code within the same parent directory tree. This plugin brings that simple and effective encapsulation concept to JavaScript/TypeScript projects.

Further reading on Go’s design:

Configuration

This rule has no options. It’s either on or off:

{
  "rules": {
    "internal-boundaries/no-outside-imports": "error"
  }
}