Node.js 21.1.0이 --experimental-detect-module 플래그 도입으로 .js 파일의 모듈 타입을 자동 감지하여 CommonJS/ES Module 런타임 선택 자동화

Context

.js 확장자나 확장자 없는 파일에서 package.json의 type 필드가 없을 경우, 개발자가 명시적으로 모듈 타입을 지정해야 하는 불편함이 있었습니다. 또한 vm.Script에서 importModuleDynamically 옵션 추가 후 V8 컴파일 캐시 히트율이 저하되어 v16.x에서 업그레이드하지 못하는 성능 회귀 문제가 발생했습니다.

Technical Solution

• ES Module 자동 감지: --experimental-detect-module 플래그로 .js 파일과 확장자 없는 파일을 구문 분석하여 ES Module 문법 감지 시 자동으로 ES Module로 실행
• 모호한 파일 처리: package.json에 type 필드가 없는 파일을 구문 분석해 ES Module 문법 발견 시 ES Module로, 미발견 시 CommonJS로 실행
• STDIN/--eval 지원: 문자열 입력을 통한 --eval과 STDIN 입력도 동일한 감지 메커니즘 적용
• V8 컴파일 캐시 복구: --experimental-vm-modules를 사용하지 않을 때 importModuleDynamically 옵션이 있어도 vm.Script의 컴파일 캐시 히트 재활성화
• 명시적 타입 지정 권장: .mjs, .cjs 확장자 또는 package.json의 type 필드로 감지 메커니즘 우회 가능

Key Takeaway

Node.js의 이중 모듈 시스템(CommonJS/ESM) 호환성 문제를 구문 분석 기반 자동 감지로 해결하되, 성능 저하를 감수하고 있으므로 package.json에 명시적 type 필드를 추가하는 것이 패키지 작성자에게 권장됩니다.