1---
2title: Avoid Circular Dependencies
3impact: CRITICAL
4impactDescription: "#1 cause of runtime crashes"
5tags: architecture, modules, dependencies
6---
7 
8## Avoid Circular Dependencies
9 
10Circular dependencies occur when Module A imports Module B, and Module B imports Module A (directly or transitively). NestJS can sometimes resolve these through forward references, but they indicate architectural problems and should be avoided. This is the #1 cause of runtime crashes in NestJS applications.
11 
12**Incorrect (circular module imports):**
13 
14```typescript
15// users.module.ts
16@Module({
17  imports: [OrdersModule], // Orders needs Users, Users needs Orders = circular
18  providers: [UsersService],
19  exports: [UsersService],
20})
21export class UsersModule {}
22 
23// orders.module.ts
24@Module({
25  imports: [UsersModule], // Circular dependency!
26  providers: [OrdersService],
27  exports: [OrdersService],
28})
29export class OrdersModule {}
30```
31 
32**Correct (extract shared logic or use events):**
33 
34```typescript
35// Option 1: Extract shared logic to a third module
36// shared.module.ts
37@Module({
38  providers: [SharedService],
39  exports: [SharedService],
40})
41export class SharedModule {}
42 
43// users.module.ts
44@Module({
45  imports: [SharedModule],
46  providers: [UsersService],
47})
48export class UsersModule {}
49 
50// orders.module.ts
51@Module({
52  imports: [SharedModule],
53  providers: [OrdersService],
54})
55export class OrdersModule {}
56 
57// Option 2: Use events for decoupled communication
58// users.service.ts
59@Injectable()
60export class UsersService {
61  constructor(private eventEmitter: EventEmitter2) {}
62 
63  async createUser(data: CreateUserDto) {
64    const user = await this.userRepo.save(data);
65    this.eventEmitter.emit('user.created', user);
66    return user;
67  }
68}
69 
70// orders.service.ts
71@Injectable()
72export class OrdersService {
73  @OnEvent('user.created')
74  handleUserCreated(user: User) {
75    // React to user creation without direct dependency
76  }
77}
78```
79 
80Reference: [NestJS Circular Dependency](https://docs.nestjs.com/fundamentals/circular-dependency)
81