모듈 해석 전략

 타입스크립트의 모듈 해석(Module Resolution)은 컴파일러가 임포트 문에서 참조하는 모듈의 정의를 찾는 과정입니다.

 이는 프로젝트의 구조와 성능에 중요한 영향을 미칩니다.

Classic vs Node 해석 전략

 1. Classic 전략

• 단순하고 오래된 방식
• 상대 경로 : 현재 파일 기준으로 해석
• 비상대 경로 : 현재 파일부터 루트까지 각 상위 디렉토리에서 검색

 2. Node 전략

• Node.js의 모듈 해석 알고리즘을 모방
• 상대 경로 : ./module, ../module 등
• 비상대 경로 : node_modules 폴더에서 검색

 예시

// Classic
import { foo } from "./foo";      // ./foo.ts 또는 ./foo.d.ts 검색
import { bar } from "bar";        // /root/src/bar.ts, /root/bar.ts 등 검색
 
// Node
import { foo } from "./foo";      // ./foo.js, ./foo.ts, ./foo/index.js 등 검색
import { bar } from "bar";        // ./node_modules/bar, ../node_modules/bar 등 검색

tsconfig.json 설정 옵션

1. baseUrl : 비상대 경로 임포트의 기준 디렉토리 설정

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

2. paths : 임포트 경로 별칭 설정

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@utils/*": ["src/utils/*"],
      "@models/*": ["src/models/*"]
    }
  }
}

3. rootDirs : 가상 디렉토리 설정

{
  "compilerOptions": {
    "rootDirs": ["src", "test"]
  }
}

상대 경로 vs 절대 경로 임포트

 상대 경로

• 장점 : 파일 위치 변경 시 임포트 문 수정 불필요
• 단점 : 깊은 중첩 구조에서 가독성 저하

 절대 경로

• 장점 : 간결하고 일관된 임포트 문
• 단점 : 파일 위치 변경 시 임포트 문 수정 필요

// 상대 경로
import { foo } from "../../../utils/foo";
 
// 절대 경로 (paths 설정 필요)
import { foo } from "@utils/foo";

타입 정의 파일 해석

• .d.ts 파일 : 자바스크립트 라이브러리의 타입 정보 제공
• @types 패키지 : DefinitelyTyped 저장소의 타입 정의

 사용자 정의 타입 정의

// global.d.ts
declare module "my-module" {
    export function myFunction(): void;
}

일반적인 모듈 해석 문제

 1. 순환 의존성

• 해결 : 인터페이스를 통한 의존성 분리, 의존성 방향 재설계

 2. 모듈 not found

• 해결 : 경로 확인, tsconfig.json 설정 검토, 패키지 설치 확인

모노레포 환경에서의 모듈 해석

 모노레포에서는 여러 프로젝트 간 의존성 관리가 중요합니다.

1. 워크스페이스 설정 (예 : Yarn Workspaces)
2. 프로젝트 간 참조 설정 (tsconfig.json의 references 필드 사용)

{
  "references": [
    { "path": "../common" },
    { "path": "../feature" }
  ]
}

Dynamic Import

 동적 임포트는 런타임에 모듈을 로드합니다.

async function loadModule() {
  const module = await import("./dynamicModule");
  module.doSomething();
}

 이 방식은 코드 스플리팅에 유용하며, 초기 로딩 시간을 줄일 수 있습니다.

번들러와 타입스크립트 컴파일러

 번들러(예 : Webpack)와 타입스크립트 컴파일러의 모듈 해석 방식이 다를 수 있습니다.

 이를 조화시키기 위해 다음을 고려해야 합니다.

1. 번들러 설정과 tsconfig.json 설정 일치시키기
2. 절대 경로 별칭 설정 동기화

 Webpack 예시

module.exports = {
  resolve: {
    alias: {
      "@utils": path.resolve(__dirname, "src/utils")
    }
  }
}

Best Practices와 모듈 구조 설계 지침

1. 일관된 임포트 스타일 사용 : 상대 경로 또는 절대 경로 중 하나로 통일
2. 경로 별칭 활용 : 긴 상대 경로 대신 별칭 사용
3. 순환 의존성 방지 : 모듈 간 의존성 그래프 주기적 검토
4. 모듈 경계 명확히 정의 : 각 모듈의 책임과 공개 API 명확화
5. 폴더 구조 최적화 : 관련 기능 그룹화, 과도한 중첩 피하기
6. 타입 정의 파일 적절히 사용 : 써드파티 라이브러리 타입 정의 관리
7. 동적 임포트 전략적 사용 : 대규모 모듈 지연 로딩
8. 번들러 설정 최적화 : 타입스크립트 컴파일러 설정과 동기화
9. 모노레포 고려 : 대규모 프로젝트에서 모듈 공유 전략 수립
10. 성능 모니터링 : 빌드 시간과 번들 크기 주기적 검토

 대규모 프로젝트 모듈 구조 예시

src/
  ├── core/             # 핵심 유틸리티 및 공통 기능
  ├── features/         # 주요 기능별 모듈
  │   ├── auth/
  │   ├── user/
  │   └── product/
  ├── api/              # API 관련 모듈
  ├── ui/               # UI 컴포넌트
  └── types/            # 전역 타입 정의