CommonJS와의 상호 운용성

Node.js는 오랫동안 ES 모듈이 아니라 CommonJS라는 모듈 방식을 써 왔고, 지금도 많은 npm 패키지와 기존 프로젝트가 CommonJS로 되어 있습니다. CommonJS는 require로 다른 모듈을 불러오고, module.exports에 넣은 값을 내보냅니다. 그래서 타입스크립트 프로젝트에서도 ES 모듈의 문법으로 CommonJS 모듈을 가져오거나, 거꾸로 코드를 CommonJS로 출력해야 하는 일이 자주 생깁니다.

이 글은 CommonJS 모듈이 내보내는 값의 모양을 먼저 보고, module 옵션에 따라 같은 소스가 어떻게 다르게 출력되는지 비교합니다. 이어서 CommonJS의 값을 ES 모듈의 기본 가져오기로 받을 때 생기는 문제와 그 해결 방법을 보고, 두 형식의 파일을 Node.js에서 함께 실행해 봅니다.

CommonJS 모듈의 모양

CommonJS에서 모듈이 내보내는 것은 module.exports에 담긴 값 하나입니다. 그 값은 객체일 수도 있고 함수나 클래스일 수도 있으며, require를 부른 쪽은 그 값을 그대로 받습니다.

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

const myUtility = require("./myUtility.js");
console.log(myUtility.add(10, 5), myUtility.subtract(10, 5));

15 5

require("./myUtility.js")는 두 함수를 가진 객체 전체를 돌려주므로 add와 subtract를 그 객체의 속성으로 부릅니다. ES 모듈에는 이름 있는 내보내기와 기본 내보내기가 따로 있지만, CommonJS에는 module.exports라는 값 하나뿐이라는 점이 두 방식이 어긋나는 출발점입니다.

위 그림처럼 module.exports 전체 값과, 그 객체의 default라는 이름의 속성은 서로 다른 것입니다. 이 차이가 어떻게 생기는지는 타입스크립트가 ES 모듈의 코드를 CommonJS로 출력하는 모습에서 드러납니다.

module 옵션에 따른 출력

다음 소스는 이름 있는 내보내기 두 개와 기본 내보내기 하나를 가집니다. 이 파일 하나를 module 설정만 바꿔 컴파일하며 출력을 비교하므로, export default가 붙은 Greeter가 출력에서 어떤 이름으로 바뀌는지를 눈여겨보세요.

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}!`);
  }
}

module을 commonjs로 두고 컴파일하면, 내보낸 이름은 모두 exports 객체의 속성이 됩니다. 다음 출력에서 exports.greeting = void 0;은 내보낼 이름을 먼저 undefined 값으로 만들어 두는 줄이고, 실제 값 "Hello"는 그 아래 줄에서 들어갑니다.

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

export default는 exports.default라는 속성으로 바뀌고, 맨 위의 __esModule 표시는 "이 객체는 ES 모듈을 CommonJS로 옮긴 것"임을 알립니다. 그래서 이 모듈을 require한 쪽이 받는 값은 Greeter 클래스가 아니라 greeting, sayHello, default를 속성으로 가진 객체입니다. 컴파일러의 버전에 따라 exports.sayHello = sayHello;처럼 함수를 연결하는 줄의 위치는 조금 다를 수 있지만, 내보낸 이름이 exports의 속성이 된다는 점은 같습니다.

module을 esnext로 두면 import와 export가 그대로 남고, 타입 표기만 지워집니다. 이렇게 같은 소스라도 module 옵션에 따라 출력의 형식이 달라지므로, 그 출력을 실행할 환경이 어느 형식으로 읽을지와 함께 정해야 합니다.

CommonJS 값을 기본 가져오기로 받기

ES 모듈의 문법으로 import myUtility from "./myUtility.js"처럼 CommonJS 모듈을 기본 가져오기로 받으면 문제가 생깁니다. ES 모듈의 기본 가져오기는 원래 default 내보내기를 받는 것인데, myUtility.js의 module.exports에는 default 속성이 없기 때문입니다.

이 차이를 메우는 것이 esModuleInterop 옵션입니다. 이 옵션이 켜져 있으면 타입스크립트는 CommonJS로 출력할 때 기본 가져오기를 __importDefault라는 도우미 함수로 감싸, __esModule 표시가 없는 모듈은 module.exports 전체를 기본 값으로 쓰게 합니다. 그래서 import myUtility from ...가 두 함수를 가진 객체 전체를 받습니다.

이 옵션을 끄면 기본 가져오기가 실제로는 require(...).default를 읽게 되어, default가 없는 CommonJS 모듈에서는 undefined를 받고 실행 중에 멈추기 쉬웠습니다. 이 동작은 오래전부터 권장되지 않았고, TypeScript 6.0에서는 esModuleInterop: false와 allowSyntheticDefaultImports: false가 폐기 예정으로 지정되어 진단이 나옵니다. 새 프로젝트에서는 이 옵션을 끄지 않습니다.

CommonJS의 module.exports = 값과 같은 내보내기를 타입스크립트에서 직접 쓰려면 export =를 씁니다. 이렇게 내보낸 모듈은 import utility = require("./utility")처럼 타입스크립트의 전용 문법으로 가져올 수 있고, esModuleInterop이 켜져 있으면 기본 가져오기로도 받을 수 있습니다.

Node.js에서 두 형식 함께 실행하기

이제 CommonJS 파일과 ES 모듈 파일이 섞인 작은 프로젝트를 실행해 봅니다. 새 폴더 ts-interop을 만들고 다음 파일을 둡니다. 확장자 .cts는 언제나 CommonJS로 출력되는 타입스크립트 파일이며, 출력 파일의 확장자는 .cjs입니다.

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": "es2022",
    "module": "nodenext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true
  },
  "include": ["src"]
}

먼저 package.json을 { "type": "commonjs" }로 저장하고 tsc -p .과 node dist/app.js를 실행합니다. 이때 app.ts도 CommonJS로 출력되어, 기본 가져오기는 __importDefault(require("./utility.cjs"))로 바뀌고 module.exports의 객체 전체를 받습니다.

15
5

이어서 package.json만 { "type": "module" }로 바꾸고 다시 컴파일해 실행합니다. 이번에는 app.ts가 ES 모듈로 출력되어 import 문이 그대로 남고, utility.cts는 확장자 때문에 여전히 CommonJS로 출력됩니다. Node.js는 ES 모듈에서 CommonJS 모듈을 기본 가져오기로 받으면 module.exports의 값을 넘겨주므로, 출력은 그대로 15와 5입니다.

위 그림처럼, 같은 소스라도 출력의 형식과 Node.js가 파일을 읽는 형식이 맞아야 실행됩니다. CommonJS로 출력했다면 그 파일이 CommonJS로 읽히도록 "type"이나 .cjs 확장자를 맞추고, ES 모듈로 출력했다면 "type": "module"이나 .mjs와 함께 상대 경로에 확장자를 적습니다. .cts와 .mts는 package.json의 "type"과 관계없이 출력 형식을 고정하므로, 한 프로젝트에서 두 형식을 섞어야 할 때 씁니다. 이 규칙은 공식 모듈 참조의 Node.js 모드에 정리되어 있습니다.

더 깊이: CommonJS에서 ES 모듈을 require하기

오랫동안 두 형식의 관계는 한쪽으로만 열려 있었습니다. ES 모듈은 CommonJS 모듈을 가져올 수 있었지만, CommonJS 모듈은 ES 모듈을 require할 수 없었습니다. Node.js의 모듈 문서에 따르면 이 기능은 v22.12.0과 v20.19.0에서 플래그 없이 쓸 수 있게 되었고, v24.15.0에서 실험 단계를 벗어났습니다. require는 ES 모듈의 네임스페이스 객체를 돌려주므로 기본 내보내기는 .default 속성에 들어 있고, 기본 내보내기가 있는 모듈이면 변환 도구와 맞추기 위한 __esModule: true 속성도 붙습니다.

제한도 있습니다. 불러오려는 모듈이나 그 모듈이 가져오는 모듈 가운데 최상위 await를 쓰는 것이 있으면, 동기적으로 실행할 수 없으므로 ERR_REQUIRE_ASYNC_MODULE 오류가 나고 그런 모듈은 import()로 불러와야 합니다. 또 ES 모듈이 export { Point as "module.exports" }처럼 "module.exports"라는 문자열 이름으로 내보내면 require가 그 값을 바로 돌려주지만, 이때 다른 이름 있는 내보내기는 CommonJS 쪽에서 보이지 않습니다. 타입스크립트는 5.8부터 module: "nodenext"에서 이런 require를 오류로 보지 않으며, 5.9에는 Node.js v20의 동작을 본뜬 안정된 설정 node20이 추가되었습니다.

정리

• CommonJS 모듈은 module.exports에 담긴 값 하나를 내보내고, require는 그 값을 그대로 돌려줍니다.
• module: "commonjs"로 출력하면 내보낸 이름은 exports의 속성이 되고, export default는 exports.default라는 속성이 됩니다.
• esModuleInterop은 __esModule 표시가 없는 CommonJS 모듈을 기본 가져오기로 받을 때 module.exports 전체를 쓰게 하며, TypeScript 6.0에서 이 옵션을 끄는 설정은 폐기 예정입니다.
• 타입스크립트에서 module.exports = 값과 같은 내보내기는 export =로 쓰고, import x = require()나 기본 가져오기로 받습니다.
• 출력의 형식과 Node.js가 파일을 읽는 형식을 "type"과 확장자로 맞추며, .cts와 .mts는 형식을 파일마다 고정합니다.

연습 문제

1. 다른 값으로 부르기

src/app.ts의 두 호출을 utility.add(7, 2)와 utility.subtract(7, 2)로 바꾸면 출력은 무엇인가요? utility.add("7", 2)는 실행 전에 허용되나요?

2. require로 받은 TypeScript 모듈

앞의 dist/myModule.js를 CommonJS 파일에서 const loaded = require("./dist/myModule.js");로 받았습니다. typeof loaded와 typeof loaded.default는 각각 무엇인가요? new loaded()는 실행되나요?

3. 형식을 고정하는 확장자

package.json이 { "type": "module" }일 때, src/utility.cts의 이름을 src/utility.ts로 바꾸면 그 파일은 어떤 형식으로 출력되나요? 그러면 export = utility;는 어떻게 되나요?

다음 글 네임스페이스 사용법에서는 모듈 이전에 타입스크립트가 코드를 묶던 방법인 네임스페이스와, 지금 그것을 쓰는 자리가 어디인지 다룹니다.