TypeScript 4.7 베타의 Node.js ESM 지원 개선

문제 상황

Next.js 12 프로젝트에서 패키지를 ESM으로 전환하는 작업 중 타입 해석 문제가 발생했다. package.json에 "type": "module"을 추가하면 TypeScript가 상대 경로 import에서 확장자를 요구했고, .js 확장자를 붙이면 실제 .ts 파일을 찾지 못하는 순환 문제였다.

// 이렇게 작성하면 컴파일 에러
import { helper } from './utils'

// 이렇게 작성하면 런타임 에러
import { helper } from './utils.ts'

TypeScript 4.7의 해결책

4.7 베타에서 moduleResolution: "node16" 또는 "nodenext" 옵션이 추가되었다. 이 설정을 사용하면 .js 확장자로 import하더라도 TypeScript가 올바르게 .ts 파일을 참조한다.

{
  "compilerOptions": {
    "module": "es2022",
    "moduleResolution": "node16",
    "target": "es2022"
  }
}

// 이제 정상 동작
import { helper } from './utils.js'

주의사항

• package.json의 exports 필드도 타입 해석에 영향을 준다
• 라이브러리 제작 시 types 필드를 명시해야 제대로 동작한다
• CJS와 ESM 듀얼 패키지는 여전히 복잡하다

당장 프로덕션 적용은 안정화를 지켜본 후 진행할 예정이다.