Typescript

axios의 타입을 어떻게 찾았는지 이해하기

비숑주인 2025. 5. 17. 17:07

TypeScript를 사용할 때 가장 매끄럽게 작동하는 기능 중 하나는 타입 자동 추론이다. axios와 같은 외부 라이브러리를 import할 때, 별도의 타입 선언 없이도 .ts 파일에서 자동으로 타입 정보를 인식하고 에러를 잡아준다. 그렇다면 TypeScript는 어떻게 axios의 타입 선언 파일(index.d.ts)을 정확히 찾아낼 수 있을까?

이번 글에서는 TypeScript의 모듈 해석 시스템(Module Resolution)에 따라, axios의 타입을 어떻게 찾는지를 내부 동작 흐름과 실제 예제를 통해 설명해보려고 한다. 

타입 선언의 두 가지 방식

TypeScript에서 타입 선언 파일을 찾는 경로는 두 가지로 나뉜다:

  1. 자체적으로 타입을 제공하는 패키지
    • 예: axios, react, lodash
    • node_modules/axios/package.json 안에 types 또는 typings 필드가 있다.
  2. @types 스코프의 커뮤니티 타입 패키지를 사용하는 경우
    • 예: jquery, express, moment
    • 타입 정의는 @types/jquery, @types/express 등 별도 패키지에서 제공된다.

따라서 TypeScript는 어떤 라이브러리가 자체 타입을 제공하는지, 아니면 @types 패키지를 찾아야 하는지를 정해진 우선순위에 따라 탐색하게 된다.

TypeScript의 모듈 해석 순서 (npm 패키지 기준)

TypeScript는 외부 모듈(예: axios)을 불러올 때, 다음과 같은 순서로 타입 선언 파일을 찾는다.

 

일반 모듈 해석 순서 (import "axios")

  1. 현재 폴더에서 node_modules가 있는지 확인
  2. node_modules/axios.ts
  3. node_modules/axios.tsx
  4. node_modules/axios.d.ts
  5. node_modules/axios/package.json 열기 → types, typings, typesVersions, main 확인
  6. node_modules/axios/index.ts
  7. node_modules/axios/index.tsx
  8. node_modules/axios/index.d.ts
  9. node_modules/@types/axios/package.json → types 확인
  10. node_modules/@types/axios.d.ts
  11. node_modules/@types/axios/index.d.ts
  12. 2~11을 다 못 찾으면 부모 폴더로 올라가 반복
  13. 최상위까지 올라가도 못 찾으면 에러 발생

실제 axios 예제 분석

test.ts 파일이 다음과 같은 경로에 있다고 가정한다. 

C:/Users/speak/tsbook/axios/test.ts

 

1. 기본 상태에서 import axios from "axios" 실행

$ npx tsc --traceResolution

 

2. 출력 로그 해석

======== Resolving module 'axios' from '.../test.ts'. ========
Loading module 'axios' from 'node_modules' folder...
Found 'package.json' at '.../node_modules/axios/package.json'.
'package.json' has 'typings' field './index.d.ts'
File '.../node_modules/axios/index.d.ts' exists - use it as a name resolution result.
======== Module name 'axios' was successfully resolved to '.../axios/index.d.ts'. ========

 

결과적으로, axios는 자체적으로 타입 선언 파일을 포함하고 있으며, package.json의 typings 필드가 "./index.d.ts"를 가리키고 있다. 따라서 TypeScript는 이 파일을 타입 정의로 사용하게 된다.

상대 경로(import './b')인 경우는 더 단순하다

import b from './b';

 

이런 상대 경로를 사용하는 경우에는 다음의 단순한 순서를 따른다:

  1. b.ts
  2. b.tsx
  3. b.d.ts
  4. b/package.json → types 확인
  5. b/index.ts
  6. b/index.tsx
  7. b/index.d.ts
  8. 위 모든 경로가 없으면 에러

주의: b.ts와 b.d.ts가 동시에 존재하면 b.ts가 우선 선택된다. 따라서 타입 정의만 제공하고자 할 때는 b.ts 대신 b.d.ts 하나만 두는 것이 좋다.

 

타입 해석 과정 시각화

📦 node_modules
 ├── axios
 │   ├── package.json   ← "typings": "./index.d.ts"
 │   └── index.d.ts     ← ✅ 타입 선언 파일
 └── @types
     └── axios          ← ❌ 필요 없음 (axios는 자체 타입 제공)

 

TypeScript가 타입을 어떻게 탐색하는지를 알면, 직접 작성하는 라이브러리나 모듈에서도 타입 제공 방식을 체계적으로 설계할 수 있다. 이를 통해 개발자의 사용성과 IDE 지원 수준을 높일 수 있다.

결론

  • TypeScript는 외부 모듈을 불러올 때, 엄격하고 정해진 탐색 순서를 따른다.
  • 타입 정보를 찾기 위해 node_modules/모듈명/package.json의 types 또는 typings 필드를 우선 확인한다.
  • 타입 정의가 없다면 @types/모듈명 아래 커뮤니티 타입을 찾는다.
  • --traceResolution 옵션을 활용하면 모듈 해석 경로를 정확히 추적할 수 있어 디버깅에 유용하다.