Skip to content

Imports

imports says what a node and everything under it may import. importedBy says the reverse: which files may import this one. Use them to set the direction dependencies flow between tiers.

"@/modules/{module}/domain/":
imports:
message: "domain/ holds the model: no framework, no persistence."
reset: true
external: [effect]
allow: ["@/modules/{module}/domain/**", "@/platform/ddd/contracts/**"]
deny:
- match: "@/modules/*/index.ts"
message: "Cross-module access goes through a port, not another module's barrel."
Field Meaning
allow repo-relative globs. An import whose target matches none is a violation.
external npm package names allowed. Omit to inherit the nearest ancestor’s; [] forbids all.
deny prohibitions, checked before allow and winning over it.
message shown when a target falls outside allow.
reset true: stop inheriting ancestors’ allow and external. Inherited deny stays.
unrestricted true: this tier has no allowlist yet; only prohibitions apply. Implies reset.

allow is matched against the resolved target: the real file after paths, workspace links and package exports are applied. external is matched by package name, so effect admits every subpath of the package. To forbid one subpath, deny its resolved path.

A node that states imports without allow must set unrestricted: true, or the manifest does not decode. An unrestricted tier still inherits every prohibition above it, and grep unrestricted lists your adoption backlog.

A target outside allow is already refused, so write a deny when a specific mistake deserves its own message.

deny:
- match: "packages/*/src/**"
matchNot: "packages/contracts/src/**"
except: "**/*.test.ts"
message: "A domain type may not cross a package boundary except through contracts."
Field Meaning
match targets this prohibits
matchNot targets carved back out of match
except importers the prohibition does not apply to
message why

A descendant cannot opt out of an ancestor’s deny; only its own except and matchNot can. Prohibitions that hold everywhere go in the top-level deny list. See Inheritance.

Write importedBy beside the file you want to protect. Any file outside allow that imports it is a violation, reported against the importer.

"*.repository.ts":
importedBy:
message: "A repository is reached from a command handler, not from a query."
allow: ["@/modules/*/commands/**", "@/modules/*/event-handlers/**"]

Reach for it when your rule starts with “a repository is…” rather than “a command handler may…”. A new tier is then refused by default, instead of needing a new outbound deny.

Field Meaning
message required. Why the restriction exists.
allow required. Globs matched against the importing file.
matchNot files in this node’s subtree, relative to its folder, left unprotected

The typical matchNot is a module’s barrel: the module is private except through index.ts.

"@/modules/{module}/":
importedBy:
message: "A module is private. Cross-module access goes through its barrel."
allow: ["@/modules/**", "**/*.test.ts"]
matchNot: [index.ts]