Skip to content
Fallow home
All docs pages

Docs home

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

FactValue
Issue typecircular-dependency
Rule id in SARIF outputfallow/circular-dependency
Commandfallow dead-code
Default severityerror
Config key in rulescircular-dependencies
Filter option--circular-deps
Suppression comment// fallow-ignore-next-line circular-dependency
Fixable with fallow fixNo
Opt-inNo

When to keep the code

  • A loop of import type imports 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, set circularDependencies.ignoreLazyImports.