typescript-circular-dependency

This skill provides a systematic approach for diagnosing and fixing circular dependency issues in TypeScript and JavaScript projects. Circular dependencies occur when modules import each other directly or indirectly, causing runtime failures where exported values evaluate to undefined because the module has not finished initializing. This tool is intended for software engineers working on complex modular codebases who encounter intermittent runtime TypeErrors or ReferenceErrors that often disappear when import statements are reordered.

• Automated cycle detection using the madge library to visualize and identify problematic dependency graphs.

• Pattern-based diagnostic strategies for common architecture issues, such as service-to-service cycles, index.ts barrel file pollution, and excessive type-value coupling.

• Practical resolution techniques including dependency injection, extraction of shared types into dedicated interface files, and the use of dynamic imports to break synchronous dependency chains.

• Implementation of type-only imports to eliminate runtime overhead for interface-only dependencies.

• CI/CD integration guidelines to prevent future regressions by embedding circular dependency checks into automated build scripts or ESLint configurations.

• Target scenarios include runtime ReferenceErrors, unexpected undefined exports, and tests that fail with module resolution issues despite valid compilation.

• Recommended for developers using frameworks like Jest, Vitest, Webpack, or Vite where module resolution timing differs from standard TS compilation.

• Users should expect to provide their source directory as input and be prepared to refactor shared logic into decoupled modules.

• Constraints include potential refactoring effort when decoupling tightly coupled services and the requirement to maintain consistent import patterns across large-scale projects.