# Enforcing module boundaries in a Node monorepo

Verified 2026-09 against <https://github.com/sverweij/dependency-cruiser>,
<https://github.com/javierbrea/eslint-plugin-boundaries> and <https://nx.dev/features/enforce-module-boundaries>.

Pick **one** of these per repository. Two overlapping rule sets means two half-maintained ones, and
the first false positive gets both disabled.

## 1. dependency-cruiser

Framework-agnostic, works on plain paths, no ESLint setup required. Install and generate a baseline:

```bash
npm i -D dependency-cruiser
npx depcruise --init
```

```js
// .dependency-cruiser.cjs
module.exports = {
  forbidden: [
    {
      name: 'no-cross-module-internals',
      comment: 'Modules talk through index.ts, never into each other\'s folders.',
      severity: 'error',
      from: { path: '^src/modules/([^/]+)/.+' },
      to: {
        path: '^src/modules/([^/]+)/.+',
        pathNot: '^src/modules/$1/.+|^src/modules/[^/]+/index\\.ts$',
      },
    },
    {
      name: 'domain-is-pure',
      comment: 'Domain code must not import transport or persistence.',
      severity: 'error',
      from: { path: '^src/modules/[^/]+/domain/.+' },
      to: { path: 'node_modules/(fastify|express|@nestjs|@prisma|drizzle-orm|ioredis)' },
    },
    {
      name: 'application-depends-on-ports-not-adapters',
      severity: 'error',
      from: { path: '^src/modules/[^/]+/application/.+' },
      to: { path: '^src/modules/[^/]+/adapters/.+' },
    },
    {
      name: 'no-circular',
      severity: 'error',
      from: {},
      to: { circular: true },
    },
    {
      name: 'no-orphans',
      severity: 'warn',
      from: { orphan: true, pathNot: '\\.d\\.ts$|^src/(app|server)\\.ts$' },
      to: {},
    },
  ],
  options: {
    tsConfig: { fileName: './tsconfig.json' },
    doNotFollow: { path: 'node_modules' },
    tsPreCompilationDeps: true,
  },
};
```

The `$1` back-reference in `to.pathNot` is what makes the first rule generic: the capture group in
`from.path` is the module name, so "not the same module, and not another module's `index.ts`" is
expressible once for every module you will ever add.

`tsPreCompilationDeps: true` matters in TypeScript projects: without it, type-only imports are
invisible, and a `domain` file importing a Prisma **type** passes a rule meant to forbid exactly that.

Run it in CI:

```bash
npx depcruise src --config .dependency-cruiser.cjs
npx depcruise src --config .dependency-cruiser.cjs --output-type dot | dot -T svg > deps.svg
```

The graph output is worth generating on a schedule — a picture of the real dependency graph is the
fastest way to show a team that the boundary they believe in does not exist.

## 2. eslint-plugin-boundaries

Better when the repository already runs ESLint on every file and you want violations in the editor.

```js
// eslint.config.js (flat config)
import boundaries from 'eslint-plugin-boundaries';

export default [
  {
    plugins: { boundaries },
    settings: {
      'boundaries/elements': [
        { type: 'domain', pattern: 'src/modules/*/domain/**' },
        { type: 'application', pattern: 'src/modules/*/application/**' },
        { type: 'adapters', pattern: 'src/modules/*/adapters/**' },
        { type: 'public', pattern: 'src/modules/*/index.ts', mode: 'file' },
        { type: 'platform', pattern: 'src/platform/**' },
      ],
    },
    rules: {
      'boundaries/element-types': ['error', {
        default: 'disallow',
        rules: [
          { from: 'domain', allow: ['domain'] },
          { from: 'application', allow: ['domain', 'application'] },
          { from: 'adapters', allow: ['domain', 'application', 'adapters', 'platform', 'public'] },
          { from: 'public', allow: ['application', 'domain'] },
          { from: 'platform', allow: ['platform'] },
        ],
      }],
    },
  },
];
```

`default: 'disallow'` is the important line: a new element type is forbidden until someone decides
where it may point, rather than silently allowed.

## 3. Nx tag constraints

If the repository already uses Nx, use what it has instead of adding a tool.

```jsonc
// apps/orders-api/project.json
{ "tags": ["scope:orders", "type:app"] }
```

```js
// eslint.config.js
'@nx/enforce-module-boundaries': ['error', {
  depConstraints: [
    { sourceTag: 'scope:orders', onlyDependOnLibsWithTags: ['scope:orders', 'scope:shared'] },
    { sourceTag: 'type:domain', onlyDependOnLibsWithTags: ['type:domain'] },
    { sourceTag: 'type:app', onlyDependOnLibsWithTags: ['type:feature', 'type:domain', 'scope:shared'] },
  ],
}]
```

Nx enforces this at the *project* level, which is stronger than a path rule — a library simply cannot
be imported — but it only works if the boundaries are real projects.

## 4. Living with the rules

- **Fail the build, do not warn.** A warning in a CI log is a rule that does not exist.
- **Add the rule with the boundary, not after.** Retrofitting onto a codebase with two hundred
  violations means starting with a baseline file and a written plan to burn it down, otherwise the
  baseline becomes permanent.
- **When a rule blocks legitimate work, change the rule in the same pull request** — with the reason
  in the commit message. An inline `// eslint-disable-next-line boundaries/element-types` with no
  comment is how the boundary dies quietly.
- **Review exceptions periodically.** Count the disables; a rising count is the signal that the
  architecture and the rule have diverged, and the rule is not always the one that is wrong.
