Circular dependencies
What a circular-dependency finding of fallow dead-code means, why it matters and how to fix it.
What it reports
Circular dependency chain detected.
Architecture explains how fallow finds it.
Why it matters
A cycle in the module import graph. Circular dependencies cause undefined behavior with CommonJS (partial modules) and initialization ordering issues with ESM. Break cycles by extracting shared code.
Example
src/a.ts imports src/b.ts, and src/b.ts imports src/a.ts.
Fix
Extract shared code to a third module, invert the dependency, or split initialization-time side effects from type-only contracts.
Facts
| Fact | Value |
|---|---|
| Issue type | circular-dependency |
| Rule id in SARIF output | fallow/circular-dependency |
| Command | fallow dead-code |
| Default severity | error |
Config key in rules | circular-dependencies |
| Filter option | --circular-deps |
| Suppression comment | // fallow-ignore-next-line circular-dependency |
Fixable with fallow fix | No |
| Opt-in | No |
When to keep the code
- A loop of
import typeimports is not a risk at run time. Fallow does not report it. - To accept one loop on purpose, list its files in
circularDependencies.allow. Fallow still reports a new loop that goes through some of these files and another file. - A dynamic
import()is part of a loop by default. To leave out the imports that load later, setcircularDependencies.ignoreLazyImports.