순환 참조 | Ray Book

순환 참조란

순환 참조 (circular dependency) 는 모듈 A가 모듈 B를 import하고, 모듈 B가 다시 모듈 A를 import하는 상황입니다.

moduleA.js --import--> moduleB.js
     ^                      |
     +------import----------+

의도치 않게 자주 발생합니다. 프로젝트가 커지면서 모듈 간 의존성이 복잡해지면, 간접적인 순환 (A → B → C → A) 도 생깁니다.

CommonJS의 순환 참조

CJS에서 순환 참조가 발생하면, 불완전한 export 객체를 받게 됩니다.

// a.js
console.log('a.js 시작');
const b = require('./b');
console.log('a.js에서 b.value:', b.value);

module.exports = { value: 'A' };
console.log('a.js 끝');

// b.js
console.log('b.js 시작');
const a = require('./a');
console.log('b.js에서 a.value:', a.value);

module.exports = { value: 'B' };
console.log('b.js 끝');

node a.js를 실행하면:

a.js 시작
b.js 시작
b.js에서 a.value: undefined    ← a.js가 아직 export를 완료하지 않음!
b.js 끝
a.js에서 b.value: B
a.js 끝

왜 이렇게 되는가

a.js 실행 시작 → require('./b') 호출
b.js 실행 시작 → require('./a') 호출
Node.js가 순환을 감지 → a.js의 현재까지의 export (아직 빈 객체) 를 반환
b.js가 받은 a에는 value가 없음 → undefined
b.js 실행 완료 → module.exports = { value: 'B' } 설정
a.js로 돌아와 b.value를 읽음 → 'B' (정상)

핵심: CJS는 순환을 만나면 실행이 완료되지 않은 모듈의 불완전한 export를 반환합니다.

ESM의 순환 참조

ESM은 라이브 바인딩 덕분에 다르게 동작합니다.

// a.mjs
console.log('a.mjs 시작');
import { valueB } from './b.mjs';

export const valueA = 'A';
console.log('a.mjs에서 valueB:', valueB);

// b.mjs
console.log('b.mjs 시작');
import { valueA } from './a.mjs';

export const valueB = 'B';
console.log('b.mjs에서 valueA:', valueA);

node a.mjs를 실행하면:

b.mjs 시작
ReferenceError: Cannot access 'valueA' before initialization

ESM의 동작 과정

구문 분석, a.mjs와 b.mjs의 import/export를 모두 파악
인스턴스화, export 바인딩을 메모리에 생성 (아직 값 없음)
평가, 의존성 그래프의 가장 깊은 곳 (b.mjs) 부터 실행

b.mjs가 먼저 실행될 때, valueA의 바인딩은 존재하지만 아직 초기화되지 않았습니다. const/let으로 선언된 변수를 초기화 전에 접근하면 TDZ (Temporal Dead Zone) 에 의해 ReferenceError가 발생합니다. CJS의 조용한 undefined와 달리, ESM은 에러를 명시적으로 던져서 문제를 빨리 발견할 수 있습니다.

함수 선언은 호이스팅된다

// a.mjs
import { greetB } from './b.mjs';
export function greetA() { return 'Hello from A'; }
console.log(greetB()); // "Hello from B", 정상!

// b.mjs
import { greetA } from './a.mjs';
export function greetB() { return 'Hello from B'; }
console.log(greetA()); // "Hello from A", 정상!

function 선언은 호이스팅되므로, 평가 순서와 관계없이 사용할 수 있습니다. 반면 const, let, 화살표 함수는 호이스팅되지만 TDZ(Temporal Dead Zone)에 의해 초기화 전에는 접근할 수 없습니다.

CJS vs ESM 순환 참조 비교

항목	CommonJS	ESM
감지 방법	캐시에서 불완전한 export 반환	초기화되지 않은 바인딩 참조
결과	`undefined` (조용한 실패)	`ReferenceError` (const/let의 TDZ)
함수 선언	순서에 따라 `undefined` 가능	호이스팅으로 정상 동작
값 변경 반영	불가 (값 복사)	가능 (라이브 바인딩)

순환 참조 감지하기

도구 활용

# madge, 의존성 그래프를 시각화하고 순환 참조를 감지
npx madge --circular src/

# 결과 예시
# Circular dependencies found!
# src/a.js → src/b.js → src/a.js

# eslint-plugin-import, lint 규칙으로 순환 참조 방지
# .eslintrc
# { "rules": { "import/no-cycle": "error" } }

수동 확인

모듈에서 import한 값이 undefined인데 분명 export하고 있다면, 순환 참조를 의심해보세요.

순환 참조 해결 전략

1. 공통 모듈 추출

순환의 원인이 되는 공유 코드를 별도 모듈로 분리합니다.

// Before: A ↔ B (순환)

// After: A → shared, B → shared (순환 해소)
// shared.js
export const config = { /* ... */ };

// a.js
import { config } from './shared';

// b.js
import { config } from './shared';

2. 의존성 역전

콜백이나 인터페이스를 사용해 직접 참조를 제거합니다.

// Before
// auth.js
import { log } from './logger';  // logger가 auth를 import하면 순환

// After
// auth.js, 의존성 주입
export function createAuth(logger) {
  return {
    login(user) {
      logger.log(`${user} 로그인`);
    }
  };
}

3. 지연 로딩

import를 함수 안으로 이동하여 실행 시점을 늦춥니다.

// a.mjs
export function getB() {
  // 필요한 시점에 동적 import
  return import('./b.mjs').then(m => m.valueB);
}

4. 모듈 구조 재설계

순환 참조는 종종 모듈 구조 설계의 문제를 알려주는 신호입니다. 모듈의 책임이 명확하지 않거나, 너무 많은 일을 하고 있을 수 있습니다.

// 좋지 않은 구조, 서로 참조
userService ↔ orderService

// 개선된 구조, 단방향 의존
userService → shared/types
orderService → shared/types
orderService → userService (단방향)

시리즈 정리

모듈 시스템 시리즈를 통해 다음을 살펴봤습니다.

모듈이 필요한 이유, 전역 스코프 오염과 IIFE의 한계
CommonJS와 ESM, 두 모듈 시스템의 동작 방식과 핵심 차이
번들링과 Tree-shaking, ESM의 정적 구조가 가능하게 하는 최적화
순환 참조, 순환 의존성의 동작과 해결 전략

JavaScript 모듈 시스템의 진화는 "전역 변수의 혼란을 어떻게 정리할 것인가"라는 질문에서 시작해, 스코프 격리, 명시적 의존성, 정적 분석이라는 답에 도달했습니다. ESM이 표준으로 자리잡으면서 tree-shaking 같은 최적화가 가능해졌고, 이는 현대 프론트엔드 빌드 시스템의 핵심이 되었습니다.