eslint-plugin-boundaries

ESLint Plugin Boundaries

Enforce architectural boundaries in your JavaScript and TypeScript projects.

ESLint Plugin Boundaries is an ESLint plugin that helps you maintain clean architecture by enforcing boundaries between different parts of your codebase. Define your architectural layers, specify how they can interact, and get instant feedback when boundaries are violated.

• Architectural Enforcement: Define dependency rules that match your project's architecture
• Multi-Layer Classification: Every file or dependency in your project can be described across three independent dimensions simultaneously — its architectural element, its own file category, and its origin. Define rules for any combination.
• Flexible Configuration: Adapt the plugin to any project structure. It works with monorepos, modular architectures, layered patterns, and any custom structure you can imagine
• Real-time Feedback: Get immediate ESLint errors when imports violate your architectural rules

Documentation

The full documentation is available on the JS Boundaries website.

Key Sections

• Overview - Introduction to the plugin and its core concepts
• Quick Start - Set up the plugin in 5 minutes
• Classification - How to classify files and folders for your architecture
• Selectors - How to match classified files, elements, and modules in your rules
• Policies - How to define dependency rules between classified files, elements, and modules
• Rules Reference - Complete documentation for all available rules
• TypeScript Support - Use with TypeScript projects

Quick Example

Install the plugin using npm:

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

Define your architectural elements:

import boundaries from "eslint-plugin-boundaries";

export default [
  {
    plugins: { boundaries },
    settings: {
      "boundaries/elements": [
        { type: "controller", pattern: "controllers/*" },
        { type: "model", pattern: "models/*" },
        { type: "view", pattern: "views/*" }
      ],
      "boundaries/files": [
        { category: "test", pattern: "**/*.test.js" }
      ]
    }
  }
];

Define your dependency rules:

{
  rules: {
    "boundaries/dependencies": [2, {
      default: "disallow",
      policies: [
        // Allow controllers to depend on models and views
        {
          from: { element: { type: "controller" } },
          allow: {
            to: { element: { types: { anyOf: ["model", "view"] } } },
          },
        },
        // Allow views to depend on models
        {
          from: { element: { type: "view" } },
          allow: {
            to: { element: { type: "model" } },
          },
        },
        // Disallow any element from importing a test file
        {
          disallow: {
            to: { file: { categories: "test" } },
          },
        },
        // Only controllers may use the `axios` package
        {
          from: { element: { type: "!controller" } },
          disallow: {
            to: { module: { origin: "external", source: "axios" } },
          },
        },
      ]
    }]
  }
}

Now ESLint will catch violations:

// In src/models/model/index.js
import View from "../../views/view"; // ❌ Error: Architectural boundary violated

Contributing

To everyone who has opened an issue, suggested improvements, fixed bugs, added features, or improved documentation: Thank you. Your contributions, no matter how small, make a real difference. Every bug report helps us improve, every feature request guides our roadmap, and every pull request strengthens the project.

Special recognition goes to those who have contributed code to the project. Your technical contributions are the foundation of what makes this plugin valuable to the community.

Want to contribute? We'd love to have you! Here are some ways to get involved:

• Report Issues: Open an issue if you find a bug or have a suggestion
• Participate in Discussions: Join the conversation on our GitHub Discussions. Review RFCs, share ideas, and help shape the future of the project.
• Contribute Code: Check out our Contributing Guidelines

License

MIT javierbrea