Org Skills

Enforcing module boundaries in a Node monorepo

Supporting material for nodejs-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

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:

npm i -D dependency-cruiser
npx depcruise --init
// .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:

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.

// 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.

// apps/orders-api/project.json
{ "tags": ["scope:orders", "type:app"] }
// 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.