module resolution과 path alias

기본 패턴

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "moduleResolution": "bundler"
  }
}

설명

• import 문법이 같아 보여도, 실제로 파일을 찾는 규칙은 런타임과 도구마다 조금씩 다릅니다. TypeScript는 이 과정을 moduleResolution 설정으로 모델링합니다.
• node16, nodenext, bundler 같은 옵션은 단순 취향이 아니라, 프로젝트가 어떤 환경에서 모듈을 해석하는지를 반영합니다. Node ESM 프로젝트인지, 번들러 중심 프론트엔드인지에 따라 맞는 값이 달라집니다.
• paths와 baseUrl은 긴 상대 경로를 줄여 가독성을 높여 주지만, TypeScript만 안다고 끝나지 않습니다. 번들러, 테스트 도구, 런타임도 같은 alias를 이해하도록 맞춰야 합니다.
• 많은 import 오류는 "문법을 틀려서"보다 "tsconfig와 런타임 해석 규칙이 어긋나서" 생깁니다. 즉 타입 검사기와 실제 실행 환경이 같은 파일을 보고 있는지 항상 확인해야 합니다.
• 좋은 설정은 화려한 alias보다 예측 가능성이 큽니다. 팀이 이해하기 쉬운 alias 개수와 일관된 디렉터리 구조를 유지하는 편이 더 오래 갑니다.

빠른 정리

주의할 점