CommonJS import

import 문법은 네 지점을 같이 맞춰야 안전하다

CommonJS 모듈을 TypeScript에서 가져올 때는 소스 문법만 보지 않는다. export 모양, 컴파일 옵션, Node 런타임, 타입 선언이 같은 방향을 가리켜야 런타임 오류와 any 누수를 줄일 수 있다.

export

module.exports

값 하나 또는 객체를 CommonJS 방식으로 내보낸다.

compile

module 옵션

CommonJS면 import가 require 호출로 변환된다.

interop

esModuleInterop

default import와 namespace import의 호환 처리를 보강한다.

types

.d.ts

타입 선언이 없으면 any 추론으로 안전성이 낮아진다.

01

내보내기 확인

module.exports인지 exports.name인지 먼저 본다.

02

컴파일 출력

dist에서 require와 import 중 무엇이 나오는지 확인한다.

03

런타임 해석

Node가 파일을 CJS로 읽는지 ESM으로 읽는지 맞춘다.

04

import 형태

default, namespace, named import 중 실제 export와 맞춘다.

05

타입 선언

@types 또는 직접 선언으로 any를 막는다.

named exports

import { add }

선언 파일이 이름을 노출

런타임 export와 타입 선언이 다름

module.exports 값

default 또는 require

esModuleInterop 설정 확인

default가 undefined로 나옴

타입 선언 없음

declare module 또는 @types

입출력 타입을 직접 좁힘

any가 서비스 경계로 퍼짐

컴파일은 성공

런타임 로더가 다르면 실행에서 깨질 수 있다.

타입은 통과

선언 파일이 실제 CommonJS export를 왜곡할 수 있다.

동작은 성공

타입 선언이 없으면 유지보수 중 오류가 늦게 드러난다.