typescript-circular-dependency

TypeScript Circular Dependency Detection and Resolution

Problem

Circular dependencies occur when module A imports from module B, which imports (directly or indirectly) from module A. TypeScript compiles successfully, but at runtime, one of the imports evaluates to undefined because the module hasn't finished initializing yet.

Context / Trigger Conditions

Common error messages:

ReferenceError: Cannot access 'UserService' before initialization

TypeError: Cannot read properties of undefined (reading 'create')

TypeError: (0 , _service.doSomething) is not a function

Symptoms that suggest circular imports:

• Import is undefined even though the export exists
• Error only appears at runtime, not during TypeScript compilation
• Moving an import statement changes which import is undefined
• Tests fail but the app works (or vice versa)
• Adding console.log at the top of a file changes behavior

Solution

Step 1: Detect the Cycle

Use a tool to visualize dependencies:

# Install madge
npm install -g madge

# Find circular dependencies
madge --circular --extensions ts,tsx src/

# Generate visual graph
madge --circular --image graph.svg src/

Or use the TypeScript compiler:

# Check for cycles (requires tsconfig setting)
npx tsc --listFiles | head -50

Step 2: Identify the Pattern

Common circular dependency patterns:

Pattern A: Service-to-Service

services/userService.ts → services/orderService.ts → services/userService.ts

Pattern B: Type imports

types/user.ts → types/order.ts → types/user.ts

Pattern C: Index barrel files

components/index.ts → components/Button.tsx → components/index.ts

Step 3: Resolution Strategies

Strategy 1: Extract Shared Dependencies

Before:

// userService.ts
import { OrderService } from './orderService';
export class UserService { ... }

// orderService.ts  
import { UserService } from './userService';
export class OrderService { ... }