CommonJS와의 상호 운용성

module 옵션이 "CommonJS"로 설정된 경우, import 문은 내부적으로 require로 변환됩니다.

하지만 타입스크립트 소스 코드에서는 여전히 import 구문을 사용하는 것이 일반적입니다.

tsconfig.json

{
  "compilerOptions": {
    "module": "CommonJS",
    // ...
  }
}

module.exports = {
  add: (a, b) => a + b,
  subtract: (a, b) => a - b
};

// app.ts
import { add, subtract } from './myUtility'; // TypeScript는 .js 파일의 export를 이해하여 타입을 추론

console.log(add(10, 5));
console.log(subtract(10, 5));

allowJs로 myUtility.js를 포함하면 JavaScript에서 내보내기를 분석할 수 있습니다. 타입 선언도 없고 JavaScript 분석 대상도 아니라면 설정에 따라 any가 되거나 선언 누락 오류가 납니다.

명시적인 타입 안전성을 위해서는 declare module 또는 @types 패키지를 통해 타입 정의를 제공하는 것이 좋습니다.

JavaScript의 분석을 켜도 모든 매개변수의 구체 타입이 자동으로 정해지는 것은 아닙니다. 위 myUtility.js에는 숫자 매개변수 선언이 없으므로, 호출 계약을 숫자로 제한하려면 선언 파일이나 주석 타입 또는 TypeScript 구현에서 이를 적어야 합니다. 정적 선언은 실제 JavaScript 구현을 대신하지 않습니다.

CommonJS와 ES 모듈 간 호환성을 높이기 위해 tsconfig.json에서 compilerOptions.esModuleInterop: true 설정을 강력히 권장합니다.

이 옵션을 활성화하면 CommonJS 모듈의 export default 유사 동작을 ES 모듈의 import default 구문으로 자연스럽게 가져올 수 있도록 컴파일러가 추가 헬퍼 코드를 생성합니다.

{
  "compilerOptions": {
    "module": "CommonJS",
    "esModuleInterop": true, // 이것을 true로 설정
    // ...
  }
}

CommonJS는 module.exports 자체에 값을 대입하거나 그 객체에 속성을 추가할 수 있습니다. exports.default는 이름이 default인 속성으로, 모듈 전체 값과 같지 않습니다.

esModuleInterop: false 상태에서 import SomeLib from 'some-lib'처럼 CommonJS 모듈 기본 내보내기를 가져오면, 실제 모듈에 default 속성이 없어 런타임 오류(undefined)가 발생할 수 있습니다.

esModuleInterop: true로 설정하면, TypeScript는 컴파일된 JavaScript 코드에 __importDefault 헬퍼 함수를 추가하여 이러한 비호환성을 자동으로 처리해줍니다.

이 비교는 기존 CommonJS 출력의 동작을 이해하기 위한 것입니다. TypeScript 6.0에서는 esModuleInterop: false에 폐기 예정 진단이 나므로 새 실습에서 꺼서 비교할 필요는 없습니다. 또한 ESM으로 그대로 출력하는 구성에서는 Node의 로더가 실제 연결을 맡습니다. 컴파일러의 헬퍼를 켠다는 사실과 모든 CommonJS 패키지의 이름 있는 내보내기가 보장된다는 주장은 구분합니다.

// date-fns v2의 subpath default export를 전제로 한 예시입니다.
// v3부터는 named export로 변경되었으므로 설치 버전에 맞는 import를 사용합니다.
import { format } from 'date-fns';
import addDays from 'date-fns/addDays'; // v2의 subpath default export

const today = new Date();
console.log(format(today, 'yyyy-MM-dd'));
console.log(addDays(today, 7));

CommonJS로 컴파일 후 Node.js에서 실행: tsconfig.json의 module을 "CommonJS"로 설정하고, 출력 .js가 CommonJS로 해석되도록 패키지의 "type": "commonjs" 등도 맞춥니다.

# tsconfig.json: "module": "CommonJS"
tsc
node dist/index.js

ES 모듈로 컴파일 후 Node.js ESM에서 실행: Node.js에서 직접 실행할 아래 예제는 module과 moduleResolution을 "NodeNext"로 맞추고, package.json의 "type": "module"로 출력 .js를 ES 모듈로 해석합니다. 상대 import에는 출력 파일 확장자도 지정합니다.

{
  "type": "module"
}

{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ESNext",
    "outDir": "./dist",
    "esModuleInterop": true,
    "moduleResolution": "NodeNext" // module과 Node.js 해석 규칙을 맞춤
  }
}

tsc
node dist/index.js # Node.js 런타임이 ES 모듈을 인식함

이 방식은 최신 Node.js 환경에서 ES 모듈의 이점을 활용할 수 있게 하지만, 모든 CommonJS 모듈과의 호환성을 보장하기 어려울 수 있습니다.

외부 패키지 없이 두 실행 형식을 비교하기

앞의 myUtility.js와 별개의 작은 실습입니다. TypeScript가 준비된 독립 폴더에 src/utility.cts와 src/app.ts를 만듭니다. .cts는 CommonJS로 출력되는 TypeScript 파일이며 결과 확장자는 .cjs입니다. export =는 이 예제에서 객체 전체를 내보냅니다.

const utility = {
  add(a: number, b: number): number { return a + b; },
  subtract(a: number, b: number): number { return a - b; },
};
export = utility;

import utility from './utility.cjs';
console.log(utility.add(10, 5));
console.log(utility.subtract(10, 5));

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "types": []
  },
  "include": ["src/**/*"]
}

최상위 package.json을 { "type": "commonjs" }로 저장한 뒤 tsc -p ., node dist/app.js를 실행합니다. 출력은 15, 5입니다. dist/utility.cjs는 객체 전체를 module.exports에 대입하고, dist/app.js는 CommonJS 가져오기 형태를 사용합니다. 헬퍼의 자세한 배치는 컴파일러 버전에 따라 달라질 수 있으므로 내보낸 전체 값과 실제 호출 결과를 확인합니다.

이제 package.json만 { "type": "module" }로 바꾸어 다시 컴파일하고 실행합니다. utility.cts의 출력은 계속 CommonJS이고 app.ts의 출력은 ESM입니다. 이 로컬 예제의 출력은 계속 15, 5입니다. dist/app.js에는 기본 import가 남고 Node가 .cjs의 전체 값을 연결합니다. 이 결과를 다른 패키지의 모든 이름 있는 내보내기까지 일반화하지 않습니다.

다른 값으로 확인하기

모듈 선언은 그대로 두고 두 호출의 인자를 7, 2로 바꾸면 각 출력은 무엇일까요? utility.add('7', 2)는 실행 전에 허용될지도 설명해 보세요. 필요한 파일을 찾지 못하는 문제와 인자 타입이 틀린 문제를 구별합니다.

출력 모드와 해석의 연결은 TypeScript 모듈 참조에서 대조할 수 있습니다. 이 실습은 외부 패키지 없이 로컬 모듈의 타입과 실행을 확인합니다. 위의 date-fns·lodash 예제를 적용할 때는 해당 패키지의 설치 버전과 내보내기 경로를 따로 확인합니다.