typescript-circular-dependency

Detect circular import dependencies in TypeScript and JavaScript projects.

1|Updated Mar 18, 2026
One-click install
npx skills add https://github.com/xxih/ai-harness-zh --skill typescript-circular-dependency-xxih
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: typescript-circular-dependency
Source: https://github.com/xxih/ai-harness-zh/tree/main/references/translations/claudeception/examples/typescript-circular-dependency
Command: npx skills add https://github.com/xxih/ai-harness-zh --skill typescript-circular-dependency-xxih

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Circular imports in TypeScript/JavaScript cause runtime errors such as undefined values, reference errors, and inconsistent behavior between test and production environments.

Core Features & Use Cases

  • Detection: Uses tools like madge or the TypeScript compiler to locate circular dependencies in a project's source files.
  • Analysis: Identifies common patterns (service-to-service, type imports, barrel files) and highlights problematic files.
  • Resolution Guidance: Recommends strategies such as extracting shared interfaces, applying dependency injection, using dynamic imports, type‑only imports, or refactoring barrel files.
  • Prevention: Provides CI and ESLint configurations to automatically fail builds when new cycles are introduced.

Quick Start

Ask the skill to scan your project directory for circular imports and suggest fixes.

Frequently Asked Questions about typescript-circular-dependency

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect circular dependencies in a TypeScript project?

To detect circular dependencies in a TypeScript project, you can use tools like madge or the TypeScript compiler to analyze your source files and identify cycles that cause undefined import errors.

Why does a circular import cause undefined values in JavaScript?

A circular import in JavaScript causes undefined values because modules evaluate iteratively, meaning a referenced module might be accessed before its exported variable is initialized during runtime execution.

How do I fix circular dependencies caused by barrel files?

To fix circular dependencies caused by barrel files, you can refactor the barrel files, extract shared interfaces into separate modules, or apply type-only imports to break the runtime execution cycles.

Can I use madge to check for circular imports in a Node.js project?

Yes, you can use madge to check for circular imports in a Node.js project by analyzing your npm or yarn workspace to detect runtime errors and visualize module cycles.

How do I prevent circular dependencies in a CI pipeline?

To prevent circular dependencies in a CI pipeline, you can integrate madge checks or configure ESLint rules to automatically fail builds whenever new module cycles are introduced into the codebase.

What is the best way to refactor service-to-service circular imports?

The best way to refactor service-to-service circular imports is to apply dependency injection or extract shared interfaces, effectively decoupling the modules to eliminate the cycle and resolve reference errors.