헷갈리는 Lodash import 구문 : import * as _는 되고 import _는 안 되는 이유

저는 Typescript를 사용하면서 Lodash라는 라이브러리를 자주 사용했습니다.

그런데 lodash를 import할 때 이런 두 가지 방식 중 어떤 건 되고, 어떤 건 안 되는 경험을 다들 해보셨나요?

import * as _ from 'lodash'; // ✅ 잘 됨
import _ from 'lodash';      // ❌ 에러 발생!

 

 

🧐 원인은? 모듈 시스템의 차이!

이 문제는 CommonJS와 ES 모듈(ESM)이라는 모듈 시스템의 차이 때문에 발생합니다.

 

 

🌱 CommonJS (Node.js에서 주로 사용)

• lodash는 전통적으로 CommonJS 방식으로 배포되어 있습니다.
• CommonJS는 module.exports를 사용하며, default export 개념이 없습니다.
• 모듈 전체를 하나의 객체로 export하는 방식입니다.

// CommonJS 방식 예시
module.exports = {
  isNil: function () { /*...*/ },
  cloneDeep: function () { /*...*/ }
};

→ 이 모듈을 import할 때는 다음과 같이 모든 export를 객체로 묶어 가져와야 합니다.

import * as _ from 'lodash'; // ✅ CommonJS 모듈에서 올바른 방식

 

🌱 ES6 모듈 (ESM)

ES6에서는 export default라는 문법이 있어, 하나의 값을 기본 내보내기(default export)로 지정할 수 있습니다.

// ES6 방식 예시
export default {
  isNil: () => {},
  cloneDeep: () => {}
};

이럴 때는 이렇게 가져옵니다 :

import _ from 'some-esm-library'; // ✅ ES6 모듈에서 올바른 방식

그런데 lodash는 기본적으로 default export를 제공하지 않기 때문에,
아래와 같은 코드는 TypeScript에서는 에러가 납니다.

import _ from 'lodash'; // ❌ Error: 'lodash' 모듈에 default export가 없습니다

 

 

💡 해결 방법 – tsconfig 설정 변경

이 문제는 TypeScript의 설정만 바꿔주면 해결됩니다.
바로 tsconfig.json에서 아래 옵션을 설정해 주세요.

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

 

esModuleInterop이란?

CommonJS 모듈을 ES6처럼 default import 가능하도록 해주는 설정입니다.

설정 후에는 이제 이렇게 써도 잘 작동합니다 :

import _ from 'lodash'; // 이제 잘 됨!

 

📎 보충 설명: allowSyntheticDefaultImports는 뭐지?

또 다른 옵션으로 allowSyntheticDefaultImports도 있는데,
이건 말 그대로 "기본 내보내기가 없어도 있는 것처럼 간주하겠다"는 의미입니다.

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true
  }
}

하지만 이건 트랜스파일 수준에서만 허용해주는 거고, 런타임에 제대로 동작하려면 결국 esModuleInterop을 설정해주는 것이 더 안전하고 확실한 방법입니다.

 

마무리

💎 lodash는 CommonJS 방식이라 import _ from 'lodash'는 기본적으로 에러 납니다.

💎 TypeScript에서 esModuleInterop: true 옵션을 주면 해결됩니다.

💎 평소에 라이브러리를 import할 때 어떤 모듈 시스템인지 확인해두면 오류를 줄일 수 있어요!