Skip to main content
Version: 7.0.0

Quick Start

Follow these steps to quickly set up ESLint Plugin Boundaries in your project. Then you can explore more advanced configurations to fit your project's needs, starting with Classification.

1. Installation​

If you have not installed them yet, install ESLint and ESLint Plugin Boundaries:

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

2. Register the Plugin​

Once installed, enable the plugin in your eslint.config.js file:

import boundaries from "eslint-plugin-boundaries";

export default [
  {
    plugins: {
      boundaries,
    },
  }
];

3. Define your Elements​

Elements classify a project by the architectural piece each file belongs to. Define them using the boundaries/elements setting.

These patterns determine how each file or dependency is classified. This step is optional on its own — as the next step explains, you only need to define at least one classification layer, elements or files.

tip

Read the Classification section for guidance on how to define the patterns for the elements and files in your project.

import boundaries from "eslint-plugin-boundaries";


export default [
  {
    plugins: {
      boundaries,
    },
    settings: {
      "boundaries/elements": [
        { type: "helper", pattern: "helpers/*" },
        { type: "component", pattern: "components/*/*" },
        { type: "module", pattern: "modules/*" }
      ],
    },
  }
];
info

This is only a basic example of configuration. The plugin can also capture path fragments from element paths so you can reuse them in rule policy selectors. Read Elements to learn the full range of descriptor options.

note

Element patterns match folders (e.g. components/*/*), not individual files. To classify files by kind — tests, styles, stories — use file descriptors in boundaries/files, as shown in the next step.

4. Categorize your Files​

This step is optional. The plugin needs at least one classification layer to work, so you only have to define either elements or file descriptors — the previous step is optional too, and defining both is not required.

While elements group files into architectural units (usually folders, such as components/Button/), file descriptors classify each file on its own, independently of the element it belongs to. They answer the question "what kind of file is this?" — a test, a style, a story — regardless of where it lives. Define them with the boundaries/files setting.

import boundaries from "eslint-plugin-boundaries";


export default [
  {
    plugins: {
      boundaries,
    },
    settings: {
      "boundaries/elements": [
        { type: "helper", pattern: "helpers/*" },
        { type: "component", pattern: "components/*/*" },
        { type: "module", pattern: "modules/*" }
      ],
      "boundaries/files": [
        { pattern: "**/*.spec.js", category: "test" },
        { pattern: "**/*.css", category: "style" }
      ],
    },
  }
];
info

File categories are independent from elements, so the same file can be element type component and file category test at the same time. Unlike element types, every matching descriptor contributes its category, so a file can carry several at once. Read Files to learn the full range of file descriptor options.

note

The rest of this guide keeps these file descriptors so you can see the file layer matched in a rule policy. If you skip this optional step, simply omit the boundaries/files setting and any rule that targets file.

5. Apply Predefined Rules​

Apply one of the predefined rule configurations as a starting point by extending it in your rules section.

tip

Use recommended for existing projects to introduce rules gradually — it allows files outside defined elements. Use strict for new projects to require all files to belong to a known element from the start.

import boundaries from "eslint-plugin-boundaries";


export default [
  {
    plugins: {
      boundaries,
    },
    settings: {
      "boundaries/elements": [
        { type: "helper", pattern: "helpers/*" },
        { type: "component", pattern: "components/*/*" },
        { type: "module", pattern: "modules/*" }
      ],
      "boundaries/files": [
        { pattern: "**/*.spec.js", category: "test" },
        { pattern: "**/*.css", category: "style" }
      ],
    },
    rules: {
      ...boundaries.configs.recommended.rules,
    },
  },
];

6. Set Dependencies Rule Policies​

Now you can define your own dependency rule policies using the boundaries/dependencies rule.

tip

Read how to use Selectors to configure your Rule Policies in detail.

import boundaries from "eslint-plugin-boundaries";


export default [
 {
   plugins: {
     boundaries,
   },
   settings: {
     "boundaries/elements": [
       { type: "helper", pattern: "helpers/*" },
       { type: "component", pattern: "components/*/*" },
       { type: "module", pattern: "modules/*" }
     ],
     "boundaries/files": [
       { pattern: "**/*.spec.js", category: "test" },
       { pattern: "**/*.css", category: "style" }
     ],
   },
   rules: {
     ...boundaries.configs.recommended.rules,
     "boundaries/dependencies": [2, {
       default: "disallow",
       policies: [
         {
           from: { element: { types: "component" } },
           allow: { to: { element: { types: "helper" } } }
         },
         {
           from: { element: { types: "module" } },
           allow: { to: { element: { types: ["component", "helper"] } } }
         },
         {
           // No element may import a test file, whatever element it belongs to
           disallow: { to: { file: { categories: "test" } } }
         }
       ]
     }]
   },
 },
];
info

You can customize the error messages reported by rule policies using message templates.

7. Next Steps​

You are all set! Now you can start enforcing architectural boundaries in your project 🎉

From here you can: