개발새발

export = 타입 이해하기 본문

Typescript

export = 타입 이해하기

비숑주인 2025. 5. 11. 02:26

TypeScript에서 jQuery와 같은 CommonJS 기반의 패키지를 사용할 때 흔히 보게 되는 문법 중 하나가 바로 export =이다. 이 문법은 일반적인 export default나 export { ... }와 다르며, TypeScript에서 CommonJS 모듈을 지원하기 위해 존재하는 독자적인 문법이다.

 

이번 글에서는 jQuery의 타입 선언 파일에서 등장하는 export = jQuery의 의미를 살펴보고, 이 문법이 실제 코드에서 어떻게 작동하는지, 그리고 esModuleInterop 설정이 어떤 영향을 미치는지 알아보도록 한다.

jQuery 타입 선언 구조

먼저 jQuery의 타입 선언 파일을 살펴보면 다음과 같은 코드가 있다.

// node_modules/@types/jquery/index.d.ts
export = jQuery;

 

여기서 jQuery는 어디에서 선언되었는지 궁금할 수 있다. 이는 다음 파일에 정의되어 있다.

// node_modules/@types/jquery/misc.d.ts
declare const jQuery: JQueryStatic;
declare const $: JQueryStatic;

 

즉, jQuery와 $는 둘 다 JQueryStatic 타입을 갖는 전역 변수로 선언되어 있으며, export = jQuery를 통해 jQuery 전체를 모듈로서 내보내는 역할을 한다.

export =는 어떤 의미인가?

export =는 TypeScript에서만 존재하는 문법으로, CommonJS 스타일의 모듈을 지원하기 위해 사용된다. 이는 ECMAScript의 export default와는 다르며, 다음과 같이 module.exports를 사용하는 CommonJS 모듈과 대응된다.

jQuery의 실제 구현 파일인 jquery.js를 보면 다음과 같은 코드가 있다.

// node_modules/jquery/dist/jquery.js
if (typeof module === "object" && typeof module.exports === "object") {
  module.exports = global.document ?
    factory(global, true) :
    function(w) {
      if (!w.document) {
        throw new Error("jQuery requires a window with a document");
      }
      return factory(w);
    };
}

 

즉, jQuery는 CommonJS 스타일로 내보내는 구조를 가지고 있으며, 이에 맞춰 타입 선언 파일에서는 export = jQuery를 사용한 것이다.

TypeScript에서 jQuery를 import하는 방법

기본 설정에서의 import

일반적으로 TypeScript에서 jQuery를 사용할 때 다음과 같이 import한다.

import $ from 'jquery';

 

이는 ECMAScript 모듈 방식의 default import 문법이다. 하지만 jQuery는 CommonJS 스타일로 작성된 모듈이므로 원칙적으로 이 방식은 오류를 발생시켜야 한다.

그런데 실제로는 에러가 발생하지 않는다. 그 이유는 tsconfig.json에서 esModuleInterop 설정이 true로 되어 있기 때문이다.

// tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

 

이 설정이 활성화되어 있으면 TypeScript는 export =로 선언된 CommonJS 모듈도 ECMAScript 모듈처럼 import $ from 'jquery' 형태로 사용할 수 있도록 허용한다.

esModuleInterop을 끄면 어떻게 되는가?

만약 다음과 같이 esModuleInterop 옵션을 끄면,

"esModuleInterop": false

 

코드에서는 다음과 같은 에러가 발생한다.

import $ from 'jquery';
// 에러: This module is declared with 'export =', and can only be used with a default import when using the 'esModuleInterop' flag.

 

즉, export =로 선언된 모듈은 esModuleInterop이 꺼진 상태에서는 기본 import 문법을 사용할 수 없다.

esModuleInterop 없이 jQuery를 import하는 방법

esModuleInterop이 false일 때는 TypeScript에서 CommonJS 모듈을 다음과 같은 방식으로 import해야 한다.

import $ = require('jquery');

 

이는 CommonJS 스타일의 require()를 타입스크립트의 import 문법과 결합한 독특한 방식이다. 이 문법은 TypeScript에서만 동작하며, export = 구문과 호환되도록 설계되었다.

하지만 이 방식은 import와 require를 동시에 사용한 형태이므로 코드 가독성이 떨어지며, 최신 프로젝트에서는 일반적으로 esModuleInterop을 활성화한 뒤 ECMAScript 모듈 스타일의 import를 사용하는 것이 권장된다.

결론

정리하자면 다음과 같다.

  • export =는 TypeScript가 CommonJS 모듈을 지원하기 위해 사용하는 독자적인 문법이다.
  • jQuery는 CommonJS 스타일로 구현된 라이브러리이며, @types/jquery에서도 이를 반영해 export = jQuery로 타입을 정의하고 있다.
  • TypeScript에서 ECMAScript 스타일로 jQuery를 import $ from 'jquery'로 사용하려면 tsconfig.json의 esModuleInterop 설정이 true여야 한다.
  • esModuleInterop이 false이면 import $ = require('jquery') 문법을 사용해야 한다.

TypeScript에서 다양한 모듈 시스템을 지원하기 위해 이런 문법이 존재하며, 상황에 맞게 올바른 import 방식을 선택해야 한다.

'Typescript' 카테고리의 다른 글

Axios 타입 분석하기  (0) 2025.05.15
스크립트 파일과 모듈 파일 이해하기  (0) 2025.05.15
jQuery 직접 타이핑하기  (0) 2025.05.10
jQuery 타입 분석하기  (1) 2025.05.10
tsc와 tsconfigjson  (0) 2025.05.10