3층 점검표

CommonJS 호환성은 컴파일, 실행, 타입 선언을 같이 본다

import 문법이 맞아 보여도 출력 JavaScript, Node.js 해석 방식, .d.ts의 export 모양이 어긋나면 실행 중 undefined나 any 누수가 발생한다.

compile

컴파일 출력

tsconfig의 module 값이 require 또는 import 출력을 결정한다.

runtime

Node 해석

package.json type과 확장자가 CJS, ESM 판정을 바꾼다.

types

타입 선언

@types와 직접 선언이 import 가능 형태를 알려준다.

소스 import

export 모양과 import 형태가 맞음

default import가 실제 default를 가정함

named, namespace, default 중 하나로 좁힌다.

컴파일 결과 
const lib = require("lib")

출력은 CJS인데 런타임은 ESM으로 읽음

dist 파일의 require, import 보존 여부를 본다.

실행 환경

Node 로더가 출력 형식과 일치

Cannot use import 또는 undefined

package.json type, 확장자, 실행 명령을 확인한다.

타입 선언

@types가 실제 export를 반영

any 또는 잘못된 default 선언

declare module로 런타임 모양을 보정한다.

01

tsconfig 확인

module, moduleResolution, esModuleInterop을 한곳에서 본다.

02

dist 확인

출력 파일이 require 기반인지 import 기반인지 확인한다.

03

Node 실행

같은 출력 파일을 실제 실행 명령으로 재현한다.

04

선언 보정

@types가 없거나 틀리면 선언 파일을 직접 좁힌다.

정렬됨

출력, 로더, 타입 선언이 같은 모듈 모양을 가리킨다.

부분 정렬

타입은 통과하지만 실행 환경에서만 깨진다.

불일치

옵션 변경보다 출력 파일과 선언 형태 확인이 먼저다.