TypeScript Interop

CommonJS와 ES 모듈을 함께 쓸 때의 확인 순서

require와 module.exports는 런타임 값 중심이고, import와 export는 정적 분석과 타입 확인에 유리하다. 둘을 섞을 때는 출력 형식과 가져오기 문법을 같이 맞춘다.

문법과 의미 차이

require vs import
CommonJS
require 함수 호출 런타임 로드
module.exports 할당 값 하나 또는 객체
ES Module
import 선언 정적 연결
export 선언 이름 기반 공개

상호 운용 점검 기준

migration checklist

esModuleInterop

CommonJS 값을 기본 가져오기처럼 다룰 때 헬퍼를 붙여 런타임 차이를 줄인다.

default import 함정

module.exports는 default 속성을 만든다는 뜻이 아니다. 타입 선언과 실제 값 모양을 함께 본다.

Node 설정

package.json의 type, 파일 확장자, tsconfig의 module 값을 같은 방향으로 맞춘다.

번들러 설정

Vite나 Webpack의 해석 규칙이 TypeScript 설정과 다르면 개발 중에는 되고 실행에서 깨질 수 있다.

점진 마이그레이션

경계 파일부터 import 형태를 고정하고, 타입 선언을 점검한 뒤 내부 모듈을 차례로 옮긴다.

점진 전환 순서

safe rollout
1

외부 패키지의 내보내기 모양 확인

2

tsconfig와 package.json 정렬

3

경계 모듈에 타입 선언 추가

4

내부 파일을 한 묶음씩 ESM으로 이동

module 호환성

import 문법만 바꾸면 끝나는 문제가 아니다. 실제 배포 파일의 모듈 형식, 런타임의 해석 규칙, 타입 선언이 같은 이야기를 하는지 확인해야 한다.