모듈 해석 전략

타입스크립트 컴파일러(tsc)는 import 또는 export 문에서 참조하는 모듈의 실제 파일을 찾아내는 복잡한 과정을 거칩니다.

이 과정을 모듈 해석(Module Resolution)이라고 하며, 타입스크립트가 소스 코드의 타입을 정확하게 확인하고 올바른 자바스크립트 코드를 생성하는 데 매우 중요합니다.

타입스크립트는 Node.js 환경의 모듈 해석 방식과 유사하게 동작하며, tsconfig.json 파일의 moduleResolution 컴파일러 옵션을 통해 이 전략을 설정할 수 있습니다.

모듈 해석의 기본 원리

타입스크립트 컴파일러는 다음 두 가지 유형의 모듈 참조를 처리해야 합니다.

모듈 해석의 핵심은 다음과 같습니다.

• 파일 찾기: import 문에 지정된 이름에 해당하는 파일을 찾아야 합니다. .ts, .tsx, .d.ts, .js, .jsx 등 다양한 확장자를 고려합니다.
• 타입 정의 파일 찾기: 실제 .js 파일 외에도 해당 모듈의 타입 정의 파일(.d.ts)을 찾아야 정확한 타입 정보를 얻을 수 있습니다.

moduleResolution 컴파일러 옵션

tsconfig.json의 compilerOptions.moduleResolution 옵션은 타입스크립트가 모듈을 해석하는 방식을 결정합니다.

아래 전략은 서로 다른 실행 환경과 세대를 대상으로 합니다.

컴파일러 버전도 먼저 확인하기

이 절의 node10, classic, baseUrl 예제는 구형 설정을 읽기 위한 설명입니다. TypeScript 6.0에서는 이 옵션들에 폐기 예정 진단이 납니다. 설치 버전은 tsc --version으로 확인하고, 새 직접 실행 예제는 NodeNext, 실제 번들러를 사용하는 예제는 그 환경의 해석 모드를 선택합니다. 아래 실습은 baseUrl 없이 명시적인 paths를 사용합니다. 구형 설정을 유지하기 위한 임시 진단 억제와 새 설정으로의 전환은 다른 결정입니다.

각 전략의 주요 특징을 살펴보겠습니다.

"node" 전략

node 전략은 구형 CommonJS 탐색에 TypeScript의 소스·선언 파일 후보를 더합니다. 아래 목록은 주요 후보의 개략이며 .jsx, 패키지 메타데이터, 타입 탐색 단계까지 포함한 완전한 탐색 순서는 아닙니다.

• 상대 경로: import { x } from './moduleA'는 다음과 같은 순서로 파일을 찾습니다.

  ./moduleA.ts

  ./moduleA.tsx

  ./moduleA.d.ts

  ./moduleA.js (실제 JavaScript 파일)

  ./moduleA/index.ts

  ./moduleA/index.tsx

  ./moduleA/index.d.ts

  ./moduleA/index.js

• 비-상대 경로: import { x } from 'moduleB'는 다음과 같은 순서로 파일을 찾습니다.

  현재 디렉터리부터 시작하여 상위 디렉터리로 이동하면서 각 node_modules 폴더를 탐색합니다.

  ./node_modules/moduleB

  ./node_modules/moduleB/package.json에서 main 또는 types 필드를 확인하여 진입점을 찾습니다.

  main이 "./dist/index.js"라면 패키지 루트 기준 경로로 해석하며, TypeScript는 대응하는 타입 파일도 탐색합니다.

  ./node_modules/moduleB.ts, ./node_modules/moduleB.d.ts 등도 탐색합니다.

예시: 프로젝트 구조

src/app.ts에서

import { helperFunction } from './utils/helper'; // 상대 경로
import { someValue } from 'some-package';       // 비-상대 경로 (node_modules에서 찾음)

helperFunction();
console.log(someValue);

이 예제는 구형 node 탐색을 설명합니다. 실제 Node.js ESM과 현대 번들러에는 각각의 전용 모드가 필요합니다.

"bundler" 전략 (TypeScript 5.0+)

bundler 전략은 Webpack, Vite, Rollup 등 현대적인 자바스크립트 번들러가 모듈을 해석하는 방식과 더 가깝습니다.

이 전략은 exports·imports 조건을 지원하면서 상대 경로의 확장자 생략 같은 번들러 관행을 허용합니다. Node.js에서 직접 실행할 ESM의 검사를 대신하지는 않습니다.

• "exports" 필드 지원: package.json의 "exports" 필드를 사용하여 조건부 내보내기(conditional exports)를 더 정확하게 해석합니다. 이는 Node.js의 새로운 모듈 시스템과 웹 번들러의 동작을 통일하는 데 중요합니다.
• import·require 조건: 사용한 구문과 모듈 설정에 맞는 패키지 조건을 선택합니다. 실제 출력의 ESM·CommonJS 판정은 실행 주체의 규칙도 확인합니다.
• Node.js의 main 필드 대신 exports 필드를 우선적으로 고려합니다.

bundler는 실제로 번들러가 출력과 의존성을 처리하는 프로젝트에서 선택합니다. Node.js가 출력 파일을 직접 로드하면 Node 전용 해석 모드를 선택합니다.

"classic" 전략 (권장되지 않음)

classic 전략은 타입스크립트 초기에 존재하던 방식입니다.

상대 경로가 아닌 모듈을 찾을 때 node_modules를 탐색하지 않고, 단순히 현재 디렉터리와 상위 디렉터리에서 .ts, .d.ts 파일을 찾는 방식으로 동작합니다.

초기 TypeScript의 AMD 등 모듈 구성을 위해 쓰이던 방식이며, 일반 script 태그의 런타임 파일 로딩 규칙을 제공하지는 않습니다.

현재는 거의 사용되지 않습니다.

추가적인 모듈 해석 관련 tsconfig.json 옵션

moduleResolution 외에도 모듈 해석에 영향을 미치는 중요한 compilerOptions가 있습니다.

• baseUrl: 비-상대 모듈 임포트의 기준이 되는 디렉터리를 지정합니다.

  이 옵션이 설정되면, 타입스크립트는 node_modules를 검색하기 전에 baseUrl을 기준으로 모듈을 찾으려고 시도합니다.

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src"
    }
  }

  // src/app.ts
  import { MyComponent } from 'components/MyComponent'; // ./src/components/MyComponent를 찾음

• paths: 모듈 경로를 컴파일러가 찾을 위치에 매핑합니다. baseUrl 없이도 사용할 수 있으며, 출력 import를 다시 쓰거나 런타임 별칭을 생성하지 않습니다.

  복잡한 상대 경로를 줄이고 모듈 구조를 추상화하는 데 매우 유용합니다.

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@app/*": ["src/app/*"],
        "@utils": ["src/utils/index.ts"]
      }
    }
  }

  import { fetchData } from '@utils'; // src/utils/index.ts
  import { User } from '@app/models/user'; // src/app/models/user.ts

• rootDirs: 여러 디렉터리가 합쳐질 것을 가정해 상대 import를 타입 검사할 가상 루트 목록입니다. 출력이나 런타임 디렉터리 구조를 직접 바꾸지는 않습니다.

  이는 빌드 시스템(번들러)이 여러 소스 디렉터리를 하나의 가상 디렉터리로 병합하는 경우에 유용합니다.

• typeRoots: 전역에 자동 포함할 타입 패키지를 지정한 디렉터리들로 제한합니다. 설정하면 기본으로 보이던 node_modules/@types도 필요한 경우 목록에 직접 넣습니다.

• types: 전역 타입 선언을 포함할 특정 @types 패키지 목록을 지정합니다.

  이 목록에 없는 @types 패키지는 전역에 자동 포함되지 않습니다. 명시적으로 import한 모듈의 타입 해석을 막는 옵션은 아닙니다.

모듈 해석 과정 디버깅

모듈 해석이 예상대로 동작하지 않을 때는 tsc 명령어에 --traceResolution 플래그를 추가하여 자세한 해석 과정을 확인할 수 있습니다.

tsc --traceResolution

이 명령어는 컴파일러가 어떤 파일을 어디서 찾으려 했는지, 어떤 규칙을 적용했는지 등 상세한 로그를 출력하여 문제를 진단하는 데 큰 도움을 줍니다.

타입 검사 성공 뒤 실행 경로를 확인하는 실습

별칭을 처리하는 실제 번들러가 없는 독립 폴더에서 진행합니다. package.json은 { "type": "module" }로 저장합니다. 아래 세 파일을 만들고, 먼저 컴파일러가 어떤 파일을 찾을지 예상해 보세요.

export function double(value: number): number {
  return value * 2;
}

import { double } from '@utils/math';
console.log(double(7));

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "types": [],
    "paths": { "@utils/*": ["./src/utils/*"] }
  },
  "include": ["src/**/*.ts"]
}

tsc -p . --traceResolution
node dist/app.js

추적 로그에서 @utils/math를 src/utils/math.ts로 해석한 부분을 찾습니다. 컴파일은 성공하지만 출력 dist/app.js의 가져오기 경로는 계속 @utils/math입니다. 이 폴더에는 해당 패키지나 실행 별칭이 없으므로 Node 직접 실행은 모듈을 찾지 못해 실패합니다. 14를 출력하지 않습니다. bundler를 선택했다는 사실만으로 실제 번들러가 설치되거나 실행된 것도 아닙니다.

이 실습을 Node 직접 실행으로 바꾸려면 두 가지를 함께 맞춥니다. tsconfig.json의 module과 moduleResolution을 모두 NodeNext로 바꾸고, 위 app.ts의 가져오기 경로를 ./utils/math.js로 바꿉니다. 다시 tsc -p ., node dist/app.js를 실행하면 14입니다. 컴파일러는 대응하는 .ts 소스를 검사하고 Node는 생성된 .js를 읽습니다.

다른 파일 이름으로 적용하기

직접 실행 구성을 유지한 상태에서 math.ts를 helper.ts로 옮기고 호출 값을 9로 바꿨다고 가정합니다. 새 가져오기 문자열과 출력은 무엇일까요? 파일 이름만 옮기고 가져오기 문자열을 그대로 두면 어떤 단계에서 문제가 드러날지도 적어보세요. 오래된 출력이 섞이지 않도록 이 변형은 새 폴더에서 실행합니다.

paths가 출력을 바꾸지 않는 이유는 공식 모듈 참조, 구형 옵션의 전환은 TypeScript 6.0 설명에서 대조할 수 있습니다.

모듈 해석 전략은 타입스크립트 프로젝트의 빌드 설정과 직접적으로 연관되어 있습니다.

프로젝트 환경(Node.js, 브라우저, 번들러 사용 여부 등)에 맞춰 moduleResolution 옵션을 올바르게 설정하는 것이 중요합니다.

Node.js 직접 실행은 Node 전용 모드, 번들러 실행은 bundler 모드를 기준으로 검토합니다.

baseUrl, paths 같은 추가 옵션을 활용하면 모듈 임포트 경로를 더 깔끔하게 관리하고 개발 경험을 개선할 수 있습니다.

모듈을 찾지 못하는 오류가 생기면 import 문자열부터 패키지의 exports와 types 필드까지 순서대로 확인하는 것이 좋습니다.

해석 실패를 줄이려면 설정 변경 전후로 실제 후보 파일, 패키지 메타데이터, 번들러 규칙이 같은 방향을 가리키는지 함께 봐야 합니다.

모듈 해석 전략을 코드에 적용하기 전, 컴파일 오류가 막아 줄 지점과 사람이 약속해야 할 지점을 나눕니다.