Enforce Project Boundaries

If you partition your code into well-defined cohesive units, even a small organization will end up with a dozen apps and dozens or hundreds of libs. If all of them can depend on each other freely, chaos will ensue, and the workspace will become unmanageable.

To help with that Nx uses code analysis to make sure projects can only depend on each other's well-defined public API. It also allows you to declaratively impose constraints on how projects can depend on each other.

Project APIs

Nx provides an enforce-module-boundaries eslint rule that enforces the public API of projects in the repo. Each project defines its public API in an index.ts (or index.js) file. If another project tries to import a variable from a file deep within a different project, an error will be thrown during linting.

To set up the lint rule, install these dependencies:

npm i @nrwl/eslint-plugin-nx @nrwl/devkit

And configure the rule in your root .eslintrc.json file:

1{
2  "plugins": ["@nrwl/nx"],
3  // ...
4  "rules": {
5    "@nrwl/nx/enforce-module-boundaries": [
6      "error",
7      {
8        /* options */
9      }
10    ]
11  }
12}
13

Tags

Nx comes with a generic mechanism for expressing constraints on project dependencies: tags.

First, use your project configuration (in project.json or package.json) to annotate your projects with tags. In this example, we will use three tags: scope:client. scope:admin, scope:shared.

1// client/package.json
2{
3  // ... more project configuration here
4  "nx": {
5    "tags": ["scope:client"]
6  }
7}
8
1// admin/package.json
2{
3  // ... more project configuration here
4  "nx": {
5    "tags": ["scope:admin"]
6  }
7}
8
1// utils/package.json
2{
3  // ... more project configuration here
4  "nx": {
5    "tags": ["scope:shared"]
6  }
7}
8

Next you should update your root lint configuration:

  • If you are using ESLint you should look for an existing rule entry in your root .eslintrc.json called "@nrwl/nx/enforce-module-boundaries" and you should update the "depConstraints":
1{
2  // ... more ESLint config here
3
4  // @nrwl/nx/enforce-module-boundaries should already exist within an "overrides" block using `"files": ["*.ts", "*.tsx", "*.js", "*.jsx",]`
5  "@nrwl/nx/enforce-module-boundaries": [
6    "error",
7    {
8      "allow": [],
9      // update depConstraints based on your tags
10      "depConstraints": [
11        {
12          "sourceTag": "scope:shared",
13          "onlyDependOnLibsWithTags": ["scope:shared"]
14        },
15        {
16          "sourceTag": "scope:admin",
17          "onlyDependOnLibsWithTags": ["scope:shared", "scope:admin"]
18        },
19        {
20          "sourceTag": "scope:client",
21          "onlyDependOnLibsWithTags": ["scope:shared", "scope:client"]
22        }
23      ]
24    }
25  ]
26
27  // ... more ESLint config here
28}
29

With these constraints in place, scope:client projects can only depend on other scope:client projects or on scope:shared projects. And scope:admin projects can only depend on other scope:admin projects or on scope:shared projects. So scope:client and scope:admin cannot depend on each other.

Projects without any tags cannot depend on any other projects. If you add the following, projects without any tags will be able to depend on any other project.

1{
2  "sourceTag": "*",
3  "onlyDependOnLibsWithTags": ["*"]
4}
5

If you try to violate the constraints, you will get an error when linting:

A project tagged with "scope:admin" can only depend on projects
tagged with "scoped:shared" or "scope:admin".

See Also

Concepts

Recipes

Reference