TypeScript의 모듈 해석 캐싱 메커니즘

들어가며

TypeScript를 사용하다가 예상치 못한 모듈 해석 관련 문제를 마주치게 되었습니다. .d.ts 파일의 위치를 변경했다가 다시 원래대로 되돌렸을 때, 이전에는 에러가 발생했는데 갑자기 정상적으로 동작하는 경우가 있습니다. 찾아보니 이는 TypeScript의 모듈 해석 캐싱 메커니즘 때문이라고 합니다. 이번 포스트에서는 이 메커니즘에 대해 자세히 알아보고, 실제 경험했던 문제와 해결 과정을 공유하겠습니다.

---

모듈 해석이란?

모듈 해석(Module Resolution)은 컴파일러가 import가 무엇을 참조하는지 알아내기 위해 사용하는 프로세스입니다. 예를 들어:

import { a } from "moduleA";

이런 import 문에서 컴파일러는 a의 모든 사용을 검사하기 위해 moduleA가 정확히 무엇을 참조하는지 알아야 합니다.

---

모듈 해석 전략

TypeScript는 두 가지 모듈 해석 전략을 제공합니다.

1. Classic (클래식)
   • TypeScript의 기본 해석 전략
   • 주로 이전 버전과의 호환성을 위해 제공됨
   • 상대적 import는 import하는 파일에 상대적으로 해석
   • 비상대적 import는 디렉터리 트리를 거슬러 올라가며 해석
2. Node (노드)
   • Node.js의 모듈 해석 메커니즘을 모방
   • node_modules 디렉터리에서 모듈을 찾음
   • package.json의 main 필드를 확인
   • index.js 파일을 찾음

---

실제 경험한 문제 상황

다음과 같은 프로젝트 구조를 가진 TypeScript 프로젝트가 있었습니다.

타입스크립트 프로젝트에서 어떻게 자바스크립트 파일을 사용하는지에 대한 두가지 방법을 공부하기 위한 예제 프로젝트였습니다.

index.ts에서는 다음과 같이 모듈을 임포트하고 있었습니다 (jsDoc 을 추가하여 사용하려 했습니다.)

import { init, exit } from "./myPackage";

init({
    url: "https://google.com",
    debug: true
});

exit(0);

 

myPackage.js

//@ts-check <- 타입스크립트 파일한테 자바스크립트 파일을 확인하라고 알리는 역할
// JSDoc : 코멘트로 이루어진 문법
// 이 파일에 작성한 내용은 타입스크립트에서 불러왔을 때 확인할 수 있음
/**
 * Initializes the project
 * @param {Object} config
 * @param {boolean} config.debug
 * @param {string} config.url
 * @returns {boolean}
 */
//누군가 깃헙과 npm 에 js로 푸시해둔 것이고, 우리가 이걸 설치했다고 가정
export function init(config){
    return true;
}

/**
 * Exits the project 
 * @param {number} code
 * @returns {number}
 */
export function exit(code){
    return code+1;
}

 

그리고 myPackage.d.ts는 다음과 같이 정의되어 있었습니다 (위의 방법 시도 전, 다른 방법을 공부하기 위해 만들어두었던 파일입니다)

interface Config {
    url: string;
    debug?: boolean;
}

declare module "myPackage" {
    function init(config: Config): boolean;
    function exit(code: number): number;
    export { init, exit };
}

 

처음에는 myPackage.d.ts 파일을 src 디렉토리 밖으로 이동했다가 다시 src 디렉토리 안으로 가져왔을 때, 이전에는 발생했던 타입 에러가 갑자기 사라지는 현상을 경험했습니다.

---

문제의 원인

이 문제가 발생한 이유는 TypeScript의 모듈 해석 캐싱 메커니즘 때문입니다:

1. 모듈 해석 캐싱

• TypeScript는 성능 최적화를 위해 모듈 해석 결과를 캐시
• 한번 모듈을 성공적으로 해석하면, 그 결과를 캐시에 저장
• 이 캐시는 TypeScript 서버가 실행되는 동안 유지

2. 캐시 초기화 조건

• TypeScript 서버 재시작
• `tsconfig.json` 변경
• 프로젝트 구조의 큰 변화
• IDE 재시작

3. 해석 과정

• 처음에는 TypeScript가 `myPackage`를 외부 패키지로 인식
• `.d.ts` 파일을 `src` 밖으로 이동했다가 다시 가져오는 과정에서 캐시가 초기화
• 모듈 해석이 새로 시작되어 상대 경로로 정확하게 해석
• 한번 성공적으로 해석된 후에는 캐시에 저장되어 계속 정상적으로 동작

---

해결 방법

이러한 모듈 해석 문제를 해결하기 위한 방법들은 다음과 같습니다

 

1. TypeScript 서버 재시작

• IDE에서 TypeScript 서버를 재시작하여 캐시 초기화

2. tsconfig.json 설정 명시

{ "compilerOptions": { 
	"moduleResolution": "node", 
    "baseUrl": ".", 
    "paths": { 
    	"myPackage": ["src/myPackage"] 
    } 
} }

 

3. 모듈 해석 추적 활성화

• --traceResolution 플래그를 사용하여 모듈 해석 과정 추적

  tsc --traceResolution

---

결론

TypeScript의 모듈 해석 캐싱 메커니즘은 성능 최적화를 위한 중요한 기능이지만, 때로는 예상치 못한 동작을 일으킬 수 있습니다. 이러한 문제를 마주쳤을 때는 캐시 초기화를 통해 해결할 수 있으며, 장기적으로는 tsconfig.json에 명시적인 설정을 추가하는 것이 좋습니다.

---

참고 자료

• TypeScript 공식 문서 - Module Resolution
• TypeScript GitHub Issues - Module Resolution Cache