CommonJS와의 상호 운용성

타입스크립트는 ES 모듈(import/export)을 강력하게 지원합니다.

하지만 Node.js 생태계에서는 오랫동안 CommonJS(require/module.exports)가 사실상 표준이었습니다.

지금도 많은 기존 프로젝트와 npm 패키지가 CommonJS를 사용합니다.

그래서 타입스크립트 프로젝트를 개발할 때 CommonJS 모듈과의 상호 운용은 여전히 자주 마주치는 과제입니다.

타입스크립트는 tsconfig.json 파일의 module 컴파일러 옵션을 통해 ES 모듈 코드를 CommonJS를 포함한 다양한 모듈 형식으로 트랜스파일(Transpile)할 수 있게 하며, 반대로 CommonJS 모듈을 타입스크립트 프로젝트에서 가져와 사용할 수 있도록 지원합니다.

module 컴파일러 옵션

tsconfig.json 파일의 compilerOptions.module 설정은 타입스크립트 코드를 어떤 모듈 시스템으로 컴파일할지 결정합니다.

• "ESNext" 또는 "ES2015" 이상: ES 모듈(import/export) 구문을 그대로 유지하거나 최신 자바스크립트 표준에 맞춰 컴파일합니다. 웹팩(Webpack), Vite 등 최신 번들러와 함께 사용하기에 적합합니다.
• "CommonJS": import와 export 구문을 CommonJS의 require와 module.exports 구문으로 변환합니다. 출력 파일을 Node.js가 CommonJS로 판정하도록 패키지 설정과 확장자도 맞춰야 합니다.

export const greeting = "Hello";

export function sayHello(name: string): void {
  console.log(`${greeting}, ${name}!`);
}

export default class Greeter {
  greet(name: string): void {
    console.log(`Greetings from Greeter, ${name}!`);
  }
}

{
  "compilerOptions": {
    "target": "es2018",
    "module": "CommonJS", // 또는 "ESNext"
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true
  }
}

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.sayHello = exports.greeting = void 0;
exports.greeting = "Hello";
function sayHello(name) {
    console.log(`${exports.greeting}, ${name}!`);
}
exports.sayHello = sayHello;
class Greeter {
    greet(name) {
        console.log(`Greetings from Greeter, ${name}!`);
    }
}
exports.default = Greeter;

export 구문이 exports.member = ... 또는 exports.default = ... 형태로 변환된 것을 볼 수 있습니다.

// target이 es2018이므로, es2018의 문법을 따르되 모듈은 esnext를 따릅니다.
export const greeting = "Hello";
export function sayHello(name) {
    console.log(`${greeting}, ${name}!`);
}
export default class Greeter {
    greet(name) {
        console.log(`Greetings from Greeter, ${name}!`);
    }
}

import/export 구문이 그대로 유지되는 것을 볼 수 있습니다.

이는 ES 모듈을 지원하는 브라우저·Node.js 또는 번들러에서 사용할 수 있습니다. Node.js에서는 패키지의 type과 파일 확장자를 함께 맞춥니다.

CommonJS 모듈 가져오기

타입스크립트 프로젝트에서 CommonJS 모듈을 가져와 사용하는 것은 매우 자연스럽습니다.

타입스크립트 컴파일러는 .js 파일이나 .d.ts (타입 정의 파일)를 기반으로 CommonJS 모듈의 타입을 추론하려고 시도합니다.

{
  "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));

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

// 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));

@types 패키지를 통한 타입 지원

라이브러리에 자체 타입 선언이 없다면 DefinitelyTyped의 타입 정의 파일(.d.ts)을 확인합니다. 자체 types와 exports를 제공하는 패키지는 그 선언을 먼저 사용합니다.

이 타입 정의 파일들은 @types/<패키지명> 형태로 npm에 배포되며, 이를 설치하면 타입스크립트가 해당 라이브러리의 타입을 인식하여 타입 안전성을 확보할 수 있습니다.

예시: lodash 라이브러리 사용 시

npm install lodash # lodash 라이브러리 설치
npm install --save-dev @types/lodash # lodash의 타입 정의 파일 설치

이제 타입스크립트 코드에서 lodash를 타입 안전하게 사용할 수 있습니다.

import _ from 'lodash'; // lodash는 기본 내보내기를 하는 CommonJS 모듈이므로, esModuleInterop: true 필요

const arr = [1, 2, 3, 4, 5];
console.log(_.sum(arr)); // 15
console.log(_.shuffle(arr)); // [4, 1, 5, 2, 3] (예시)

Node.js 환경에서 타입스크립트 실행 시 고려사항

현재 Node.js는 별도 실험 플래그 없이 ES 모듈을 지원합니다. .mjs 또는 package.json의 "type": "module" 등으로 파일 형식을 명확히 지정합니다.

Node.js 프로젝트에서 타입스크립트를 사용할 때는 다음과 같은 방식들을 고려할 수 있습니다.

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

{
  "type": "module"
}

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

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

CommonJS와의 상호 운용성은 타입스크립트 개발에서 피할 수 없는 중요한 부분입니다.

tsconfig.json의 module과 esModuleInterop 옵션을 적절히 설정하고, 필요하다면 @types 패키지를 활용하여 CommonJS 라이브러리에 대한 타입 정의를 추가함으로써, 타입스크립트의 타입 안전성을 유지하면서도 광범위한 자바스크립트 생태계를 활용할 수 있습니다.

마지막으로 실제 프로젝트에서 오류를 줄이려면 컴파일 출력, 런타임 해석, 타입 선언을 한 번에 점검해야 합니다.

CommonJS 호환 문제는 import 문법만 보고 판단하기 어렵기 때문에, 컴파일 결과와 Node.js 실행 규칙, 타입 선언 형태를 같은 줄에 놓고 비교해야 합니다.