Architecture
Find import cycles and imports that break your layer rules with fallow architecture, and break or accept each one.
Two problems make a codebase hard to change as it grows. Modules import each other in a loop, so no module can change alone. Code in one layer imports code that it must not use, for example a utility that imports a service. When a price formatter imports the price catalog, each change to the catalog can break the formatter. Each test of the formatter then loads the catalog too. fallow architecture finds both problems.
npx fallow architecture
What fallow finds
The demo project has neither problem, so this page adds both. src/lib/format.ts gets a formatSku function that imports lookupPrice from src/services/catalog.ts. catalog.ts gets a sampleOrder function that imports createOrder from src/services/orders.ts, which already imports catalog.ts. A config file sets three zones, as in Boundaries below. The report:
── Architecture ─────────────────────────────────────
● Circular dependencies (1)
src/services/catalog.ts
→ orders.ts → catalog.ts
Import cycles that can cause initialization failures and prevent tree-shaking
https://fallow.tools/docs/explanations/dead-code/#circular-dependencies
● Boundary violations (1)
src/lib/format.ts:1 → src/services/catalog.ts (lib → services)
Imports that cross defined architecture zone boundaries
https://fallow.tools/docs/explanations/dead-code/#boundary-violations
✗ 1 circular dependency · 1 boundary violation (0.10s)
| Part | Meaning |
|---|---|
src/services/catalog.ts and → orders.ts → catalog.ts | The files of the cycle, in import order. The last file imports the first file again. |
src/lib/format.ts:1 | The file and the line of the import that breaks a rule. |
→ src/services/catalog.ts | The file that the import loads. |
(lib → services) | The zone of the importing file and the zone of the target. A zone is a group of files that your config names. No rule lets lib import services. |
The main kinds of architecture findings are:
| Finding | What it is | Rule |
|---|---|---|
| Circular dependency | Files that import each other in a loop, directly or through other files. | circular-dependency |
| Re-export cycle | Barrel files that export from each other in a loop. No file in the loop declares the names. | re-export-cycle |
| Package cycle | Workspace packages that import each other in a loop. | package-cycle |
| Boundary violation | An import from one zone to a zone that your rules do not allow. | boundary-violation |
With boundaries, fallow can also report a file that matches no zone (boundary-coverage) and a call that the zone of the file forbids (boundary-call-violation).
How fallow decides
Fallow reads the same graph of imports as for dead code, so both analyses see the same imports.
Cycles
A cycle is a path of imports that returns to the file where it starts. Fallow reports cycles of any length.
- An
import typeloads no code when the program runs. A cycle in which each import is type-only is not a finding. - A dynamic
import()counts as an edge. To skip the imports that load later, setcircularDependencies.ignoreLazyImports. - A package cycle uses the imports in the code, not the dependencies in
package.json. Imports from test files and config files do not count. A type-only import counts, because a declaration build can still need the other package first.
A cycle is a risk, because JavaScript runs the modules of a cycle in an order that depends on the first import. A module can then read an export of another module before that module has set it, and get undefined. A re-export cycle is almost always a mistake: an import through the loop finds no declaration.
Boundaries
Fallow finds cycles with no config. A boundary is different, because it needs your rules. A zone is a named group of files, set by glob patterns. A rule lists the zones that one zone may import:
// .fallowrc.json
{
"boundaries": {
"zones": [
{ "name": "reports", "patterns": ["src/reports/**"] },
{ "name": "services", "patterns": ["src/services/**"] },
{ "name": "lib", "patterns": ["src/lib/**", "src/utils/**"] }
],
"rules": [
{ "from": "reports", "allow": ["services", "lib"] },
{ "from": "services", "allow": ["lib"] },
{ "from": "lib", "allow": [] }
]
}
}
These rules make three layers: each zone may import only the zones below it. In the picture, the solid arrows are the imports that the rules allow. The dotted arrow is the import in format.ts that breaks the rule of lib:
Diagram source
flowchart TD
reports["reports: src/reports"]
services["services: src/services"]
lib["lib: src/lib and src/utils"]
reports -->|allowed| services
reports -->|allowed| lib
services -->|allowed| lib
lib -. "format.ts:1 imports catalog.ts" .-> servicesA file belongs to the first zone that matches it. Files in one zone can always import each other. An empty allow list means that the zone may import no other zone. Fallow checks each file that it analyzes, also an unused file. Boundary configuration explains the presets, the zones that fallow finds by itself, and each other option.
To see the zones and the rules that fallow uses, run:
npx fallow list --boundaries
Boundaries: 3 zones, 3 rules
Zones:
reports 3 files src/reports/**
services 3 files src/services/**
lib 6 files src/lib/**, src/utils/**
Rules:
reports → services, lib
services → lib
lib (isolated, no imports allowed)
Before you change a file, fallow guard <file> shows the zones that the file may import.
Policy rules
Some project rules forbid a call or a package in a part of the code. A rule pack is a JSON file of such rules, for example "do not call Date in the domain code" or "do not import moment". Fallow reports each call or import that breaks a rule as a policy violation. Load a pack with the rulePacks key, and run fallow architecture --policy to see only these findings. fallow rule-pack creates and checks packs.
Act on a finding
Break a cycle
Look at the files of the cycle and find the import that you can remove most easily. In the example, catalog.ts imports createOrder only for sampleOrder, so that function can move to orders.ts. These fixes work for most cycles:
| Situation | Fix |
|---|---|
| Two files share a function or a constant. | Move it to a third file that both files import. |
| A low-level file calls back into a high-level file. | Pass the function as a parameter, so that the low-level file does not import it. |
| One side needs only a type. | Change the import to import type. |
| A re-export cycle. | Remove one export * from line in one file of the loop. |
| A package cycle. | Move the shared code to a package that both packages can import. |
One removed import breaks the cycle. Run fallow architecture --cycles again: a large group of files can hold more cycles than the report lists.
To accept one cycle, list its files in circularDependencies.allow. Fallow then reports a new cycle through the same files again.
Fix or accept a boundary violation
Change the import, so that it follows the rules. In the example, formatSku in src/lib/format.ts needs a price from services. Move formatSku to services, or pass the price as a parameter.
When the import is correct and the rule is too strict, add the zone to the allow list of the rule. To accept one import, add a comment on the line above it:
// fallow-ignore-next-line boundary-violation
import { lookupPrice } from "../services/catalog";
Fail a run
Circular dependencies and boundary violations have the severity error by default, so the example run exits with code 1. Re-export cycles, package cycles and policy violations have the severity warn. Add --fail-on-issues to fail on them too.
When you add boundaries to an existing codebase, the first run often lists many violations. Start with the rule at warn, and set it to error when no violation is left:
// .fallowrc.json
{
"rules": {
"boundary-violation": "warn"
}
}
To fail only on the cycles and violations that a change adds, see Changed code and baselines.
What fallow cannot see
- An import that the code builds when it runs. It is not part of the graph.
- A call through a value that another zone passes in. A boundary rule checks imports only.
- Each path of a large cycle. A cycle with many files can hold many paths. Fallow lists a limited number of cycles for each group of files that import each other.
Reference
fallow dead-code also reports architecture findings, in its Structure section. Its options --circular-deps, --re-export-cycles, --package-cycles, --boundary-violations and --policy-violations are deprecated aliases of fallow architecture --cycles, --boundaries and --policy.
fallow architecture: each option, the JSON output and the exit codes.- Boundary configuration: presets, zones and rules.
- Architecture config: each key and its default.