Skip to content
Fallow home
All docs pages

Docs home

Package cycles

What a package-cycle finding of fallow dead-code means, why it matters and how to fix it.

What it reports

Two or more workspace packages import each other in a loop.

Architecture explains how fallow finds it.

Why it matters

Workspace packages whose resolved imports form a cycle. Each workspace package is a node and each resolved import from one package to another is an edge, so a package cycle can exist when no file-level cycle exists. Imports from test, spec, story, fixture and tooling config files are not edges, because those files are not part of the package build. Packages in a cycle cannot be built in dependency order. Each hop shows one example import and a type_only flag; a type-only hop still matters for declaration builds. To fix this, remove the imports on one hop, for example by moving the shared code to a package that both packages import.

Example

packages/api imports @acme/db, and packages/db imports a type from @acme/api.

Fix

Remove the imports on one hop. Move the code that both packages need into a third package that both packages import.

Facts

FactValue
Issue typepackage-cycle
Rule id in SARIF outputfallow/package-cycle
Commandfallow dead-code
Default severitywarn
Config key in rulespackage-cycle
Filter option--package-cycles
Suppression comment// fallow-ignore-next-line package-cycle
Fixable with fallow fixNo
Opt-inNo

Note. Requires a workspace with two or more packages.

When to keep the code

  • A loop where each step is import type cannot fail at run time. It still blocks a build in package order.
  • When your build tool does not build the packages in order, set the rule to off.

Notes

A suppression comment above an import removes that import from the package graph. The loop goes away only when you suppress each import of one step.