typescript-circular-dependency

Run madge with the --circular flag against your source directory, for example: madge --circular --extensions ts,tsx src/. It lists every cycle and can generate a visual dependency graph with the --image option.

This error usually indicates a circular import where a module is accessed before it finishes initializing. Break the cycle by extracting shared interfaces into a separate file, using dependency injection, or switching to type-only imports.

Jest and Vitest may resolve modules in a different order than your bundler, exposing circular dependencies that the bundler tolerates. Detect the cycle with madge and restructure the imports so no module depends on itself transitively.

Yes, import type is erased at compile time and creates no runtime dependency, so it cannot participate in a cycle. Use it whenever you only need a type or interface rather than a runtime value.

Add a madge --circular check as an npm script and run it in your CI pipeline, or configure the ESLint import plugin with the import/no-cycle rule. Both approaches fail the build when a new cycle is introduced.