Node.js ESM 전환 시 ERR_REQUIRE_ESM 해결 및 Dual-format 빌드 전략

Node.js "type": "module" vs CommonJS: 7 Real Errors and the .cjs/.mjs Fix Map (2026)

スシロー2026년 6월 2일8분intermediate

AI 요약

Context

Node.js 환경에서 CommonJS(CJS)에서 ECMAScript Modules(ESM)로 전환 시 발생하는 모듈 시스템 간 호환성 충돌 분석. package.json의 "type": "module" 설정으로 인해 기존 .js 파일의 파싱 방식이 강제로 변경되며 발생하는 런타임 에러 해결 필요.

Technical Solution

package.json의 "type" 필드 기반 .js 파일 해석 규칙을 활용한 모듈 시스템 정의
확장자 .cjs 및 .mjs를 통한 package.json 설정 무시 및 명시적 모듈 타입 강제 지정
createRequire(import.meta.url)를 통한 ESM 내 CJS 의존성 로드 브릿지 구현
Conditional Exports 맵 설계를 통한 ESM/CJS Dual-format 라이브러리 배포 구조 구축
import.meta.url 및 fileURLToPath 조합을 통한 ESM 환경 내 __dirname 대체 로직 구현
라이브러리 배포 시 types -> import -> require 순서의 조건부 내보내기 우선순위 적용

실천 포인트

1. 신규 프로젝트는 첫 커밋부터 "type": "module" 설정 권장

2. 기존 프로젝트는 .mjs 전환 후 마지막에 전역 플래그 변경 전략 채택

3. Dual-format 빌드 시 exports 맵에서 types 필드를 최상단에 배치

4. CJS 전용 설정 파일은 .cjs 확장자로 명시적 분리

태그

#Conditional Exports #Module System #Node.js #CommonJS #ESM

원문 읽기