JS Boundaries

Lint your architecture, not just your syntax.

An ESLint plugin for JavaScript and TypeScript projects. Classify your files, write policies for who may depend on whom, and get an ESLint error the moment a boundary is crossed. In your IDE, in CI, with nothing new to run.

Documentation: jsboundaries.dev · Quick start

Installation

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

How it works

From folder tree to enforced architecture in three edits.

1. Classify files and elements

Element descriptors match folders. File descriptors match files on their own, so a file can be a component and a test at the same time. You only need one of the two to start.

settings: {
  "boundaries/elements": [
    { type: "helper",    pattern: "helpers/*" },
    { type: "component", pattern: "components/*/*" },
    { type: "module",    pattern: "modules/*" },
  ],
  "boundaries/files": [
    { pattern: "**/*.spec.js", category: "test" },
  ],
}

2. Write the policies

Pick a default, then allow or disallow by any combination of element type, file category, module origin and dependency kind. Captured path fragments let one policy cover a whole family of elements.

"boundaries/dependencies": [2, {
  default: "disallow",
  policies: [
    { from: { element: { type: "component" } },
      allow: { to: { element: { type: "helper" } } } },
    { from: { element: { type: "module" } },
      allow: { to: { element: { types: ["component", "helper"] } } } },
    { disallow: { to: { file: { categories: "test" } } },
      message: "Never import test files from {{ from.element.types.[0] }}s" },
  ],
}]

3. Read the error where you wrote the import

Violations are ordinary ESLint errors: editor squiggles, CI failures, templated messages with the element types on both sides. Three more rules catch files outside your architecture, unknown dependencies and ignored ones.

src/helpers/format/index.js
  1:22  error  There is no policy allowing dependencies from
         elements of type "helper" to elements of type "component"
         boundaries/dependencies

✖ 1 problem (1 error, 0 warnings)

The quick start puts these pieces together in a complete eslint.config.js.

Packages

This repository holds the packages of JS Boundaries:

Package	Description
eslint-plugin-boundaries	The ESLint plugin, also published as @boundaries/eslint-plugin.
@boundaries/elements	Entity descriptors and matchers for @boundaries tools.
@boundaries/config	Normalization and validation of the settings and rule options of the plugin, without ESLint.
@boundaries/policies	Evaluation of the dependency policies of the plugin and their messages, without ESLint.

Contributing

Thank you to everyone who has reported issues, suggested improvements or contributed code. To get involved, open an issue, join the discussions or read the contributing guidelines.

License

MIT © javierbrea