TypeScript 모듈 해석: import 경로 전략 해부

TypeScript의 모듈 해석 시스템은 확장 가능하고 유지 관리 가능한 애플리케이션을 구축하는 데 중요한 측면입니다. import 경로를 기반으로 TypeScript가 모듈을 찾는 방법을 이해하는 것은 코드베이스를 구성하고 일반적인 함정을 피하는 데 필수적입니다. 이 포괄적인 가이드에서는 TypeScript 모듈 해석의 복잡성을 탐구하고, 클래식 및 노드 모듈 해석 전략, tsconfig.json의 baseUrl 및 paths 역할, import 경로를 효과적으로 관리하기 위한 모범 사례를 다룹니다.

모듈 해석이란?

모듈 해석은 TypeScript 컴파일러가 코드의 import 문을 기반으로 모듈의 위치를 결정하는 프로세스입니다. import { SomeComponent } from './components/SomeComponent';를 작성할 때 TypeScript는 SomeComponent 모듈이 실제로 파일 시스템에 어디에 있는지 파악해야 합니다. 이 프로세스는 모듈을 찾는 방법을 정의하는 규칙 및 구성 세트에 의해 제어됩니다.

잘못된 모듈 해석은 컴파일 오류, 런타임 오류 및 프로젝트 구조를 이해하기 어렵게 만들 수 있습니다. 따라서 모듈 해석에 대한 견고한 이해는 모든 TypeScript 개발자에게 중요합니다.

모듈 해석 전략

TypeScript는 tsconfig.json의 moduleResolution 컴파일러 옵션을 통해 구성되는 두 가지 기본 모듈 해석 전략을 제공합니다.

Classic: TypeScript에서 사용되는 원래 모듈 해석 전략입니다.
Node: Node.js 모듈 해석 알고리즘을 모방하여 Node.js를 대상으로 하거나 npm 패키지를 사용하는 프로젝트에 이상적입니다.

Classic 모듈 해석

classic 모듈 해석 전략은 둘 중에서 더 간단합니다. 모듈을 간단한 방식으로 검색하며, 가져오는 파일에서 디렉토리 트리를 위로 이동합니다.

작동 방식:

가져오는 파일이 포함된 디렉토리에서 시작합니다.
TypeScript는 지정된 이름과 확장자(.ts, .tsx, .d.ts)를 가진 파일을 찾습니다.
찾지 못하면 상위 디렉토리로 이동하여 검색을 반복합니다.
모듈을 찾거나 파일 시스템의 루트에 도달할 때까지 이 프로세스가 계속됩니다.

예시:

다음 프로젝트 구조를 고려해 보세요.


project/
├── src/
│   ├── components/
│   │   ├── SomeComponent.ts
│   │   └── index.ts
│   └── app.ts
├── tsconfig.json

app.ts가 import { SomeComponent } from './components/SomeComponent'; import 문을 포함하는 경우, classic 모듈 해석 전략은 다음을 수행합니다.

src 디렉토리에서 ./components/SomeComponent.ts, ./components/SomeComponent.tsx 또는 ./components/SomeComponent.d.ts를 찾습니다.
찾지 못하면 상위 디렉토리(프로젝트 루트)로 이동하여 검색을 반복하지만, 이 경우 컴포넌트가 src 폴더 내에 있으므로 성공할 가능성은 낮습니다.

제한 사항:

복잡한 프로젝트 구조를 처리하는 데 있어 유연성이 제한적입니다.
node_modules 내 검색을 지원하지 않아 npm 패키지에 의존하는 프로젝트에 적합하지 않습니다.
장황하고 반복적인 상대 import 경로를 초래할 수 있습니다.

사용 시기:

classic 모듈 해석 전략은 일반적으로 간단한 디렉토리 구조와 외부 종속성이 없는 매우 작은 프로젝트에만 적합합니다. 현대 TypeScript 프로젝트는 거의 항상 node 모듈 해석 전략을 사용해야 합니다.

Node 모듈 해석

node 모듈 해석 전략은 Node.js에서 사용되는 모듈 해석 알고리즘을 모방합니다. 따라서 Node.js를 대상으로 하거나 npm 패키지를 사용하는 프로젝트에 선호되는 선택이며, 일관되고 예측 가능한 모듈 해석 동작을 제공합니다.

작동 방식:

node 모듈 해석 전략은 node_modules 내에서 검색하는 것을 우선시하고 다양한 파일 확장자를 처리하는 더 복잡한 규칙 세트를 따릅니다.

비상대 import: import 경로가 ./, ../ 또는 /로 시작하지 않으면 TypeScript는 node_modules에 있는 모듈을 참조한다고 가정합니다. 다음 위치에서 모듈을 검색합니다.

현재 디렉토리의 node_modules.
상위 디렉토리의 node_modules.
...이하 파일 시스템의 루트까지.

상대 import: import 경로가 ./, ../ 또는 /로 시작하는 경우 TypeScript는 이를 상대 경로로 취급하고 지정된 위치에서 모듈을 검색하며 다음을 고려합니다.

먼저 지정된 이름과 확장자(.ts, .tsx, .d.ts)를 가진 파일을 찾습니다.
찾지 못하면 지정된 이름의 디렉토리를 찾고 해당 디렉토리 내에서 index.ts, index.tsx 또는 index.d.ts라는 파일을 찾습니다(예: import가 ./components인 경우 ./components/index.ts).

예시:

lodash 라이브러리에 대한 종속성이 있는 다음 프로젝트 구조를 고려해 보세요.


project/
├── src/
│   ├── utils/
│   │   └── helpers.ts
│   └── app.ts
├── node_modules/
│   └── lodash/
│       └── lodash.js
├── tsconfig.json

app.ts가 import * as _ from 'lodash'; import 문을 포함하는 경우, node 모듈 해석 전략은 다음을 수행합니다.

lodash가 비상대 import임을 인식합니다.
프로젝트 루트의 node_modules 디렉토리에서 lodash를 검색합니다.
node_modules/lodash/lodash.js에서 lodash 모듈을 찾습니다.

helpers.ts가 import { SomeHelper } from './SomeHelper'; import 문을 포함하는 경우, node 모듈 해석 전략은 다음을 수행합니다.

./SomeHelper가 상대 import임을 인식합니다.
src/utils 디렉토리에서 ./SomeHelper.ts, ./SomeHelper.tsx 또는 ./SomeHelper.d.ts를 찾습니다.
이러한 파일이 없으면 SomeHelper라는 디렉토리를 찾고 해당 디렉토리 내에서 index.ts, index.tsx 또는 index.d.ts를 검색합니다.

장점:

node_modules 및 npm 패키지를 지원합니다.
Node.js와 일관된 모듈 해석 동작을 제공합니다.
node_modules의 모듈에 대해 비상대 import를 허용하여 import 경로를 단순화합니다.

사용 시기:

node 모듈 해석 전략은 대부분의 TypeScript 프로젝트, 특히 Node.js를 대상으로 하거나 npm 패키지를 사용하는 프로젝트에 권장되는 선택입니다. classic 전략에 비해 더 유연하고 강력한 모듈 해석 시스템을 제공합니다.

`tsconfig.json`에서 모듈 해석 구성

tsconfig.json 파일은 TypeScript 프로젝트의 중앙 구성 파일입니다. 모듈 해석 전략을 포함한 컴파일러 옵션을 지정하고 TypeScript가 코드를 처리하는 방법을 사용자 지정할 수 있습니다.

다음은 node 모듈 해석 전략이 있는 기본 tsconfig.json 파일입니다.


{
  "compilerOptions": {
    "moduleResolution": "node",
    "target": "es5",
    "module": "commonjs",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist",
    "sourceMap": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules"
  ]
}

모듈 해석과 관련된 주요 compilerOptions:

moduleResolution: 모듈 해석 전략(classic 또는 node)을 지정합니다.
baseUrl: 비상대 모듈 이름 확인을 위한 기본 디렉토리를 지정합니다.
paths: 모듈에 대한 사용자 지정 경로 매핑을 구성할 수 있습니다.

`baseUrl` 및 `paths`: import 경로 제어

baseUrl 및 paths 컴파일러 옵션은 import 경로를 확인하는 방법을 제어하는 강력한 메커니즘을 제공합니다. 절대 import를 사용하고 사용자 지정 경로 매핑을 생성하여 코드의 가독성과 유지 관리성을 크게 향상시킬 수 있습니다.

`baseUrl`

baseUrl 옵션은 비상대 모듈 이름 확인을 위한 기본 디렉토리를 지정합니다. baseUrl이 설정되면 TypeScript는 현재 작업 디렉토리가 아닌 지정된 기본 디렉토리에 대해 비상대 import 경로를 확인합니다.

예시:

다음 프로젝트 구조를 고려해 보세요.


project/
├── src/
│   ├── components/
│   │   ├── SomeComponent.ts
│   │   └── index.ts
│   └── app.ts
├── tsconfig.json

tsconfig.json이 다음을 포함하는 경우:


{
  "compilerOptions": {
    "moduleResolution": "node",
    "baseUrl": "./src"
  }
}

그러면 app.ts에서 다음과 같은 import 문을 사용할 수 있습니다.


import { SomeComponent } from 'components/SomeComponent';

다음 대신:


import { SomeComponent } from './components/SomeComponent';

TypeScript는 baseUrl로 지정된 ./src 디렉토리에 대해 components/SomeComponent를 확인합니다.

baseUrl 사용의 이점:

특히 중첩된 디렉토리에서 import 경로를 단순화합니다.
코드를 더 읽기 쉽고 이해하기 쉽게 만듭니다.
잘못된 상대 import 경로로 인한 오류 위험을 줄입니다.
import 경로에서 물리적 파일 구조를 분리하여 코드 리팩토링을 용이하게 합니다.

`paths`

paths 옵션을 사용하면 모듈에 대한 사용자 지정 경로 매핑을 구성할 수 있습니다. import 경로를 확인하는 방법을 제어하는 더 유연하고 강력한 방법을 제공하여 모듈에 대한 별칭을 만들고 import를 다른 위치로 리디렉션할 수 있습니다.

paths 옵션은 각 키가 경로 패턴을 나타내고 각 값이 경로 교체를 나타내는 배열인 객체입니다. TypeScript는 import 경로를 경로 패턴과 일치시키려고 시도하고, 일치하는 항목을 찾으면 import 경로를 지정된 교체 경로로 바꿉니다.

예시:

다음 프로젝트 구조를 고려해 보세요.


project/
├── src/
│   ├── components/
│   │   ├── SomeComponent.ts
│   │   └── index.ts
│   └── app.ts
├── libs/
│   └── my-library.ts
├── tsconfig.json

tsconfig.json이 다음을 포함하는 경우:


{
  "compilerOptions": {
    "moduleResolution": "node",
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
      "@mylib": ["../libs/my-library.ts"]
    }
  }
}

그러면 app.ts에서 다음과 같은 import 문을 사용할 수 있습니다.


import { SomeComponent } from '@components/SomeComponent';
import { MyLibraryFunction } from '@mylib';

TypeScript는 @components/* 경로 매핑을 기반으로 @components/SomeComponent를 components/SomeComponent로 확인하고, @mylib 경로 매핑을 기반으로 @mylib를 ../libs/my-library.ts로 확인합니다.

paths 사용의 이점:

모듈에 대한 별칭을 만들어 import 경로를 단순화하고 가독성을 향상시킵니다.
import를 다른 위치로 리디렉션하여 코드 리팩토링 및 종속성 관리를 용이하게 합니다.
물리적 파일 구조를 import 경로에서 추상화하여 변경 사항에 더 탄력적인 코드를 만들 수 있습니다.
유연한 경로 일치를 위해 와일드카드 문자(*)를 지원합니다.

paths의 일반적인 사용 사례:

자주 사용되는 모듈에 대한 별칭 만들기: 예를 들어, 유틸리티 라이브러리 또는 공유 컴포넌트 세트에 대한 별칭을 만들 수 있습니다.
환경에 따라 다른 구현으로 매핑: 예를 들어, 테스트 목적으로 인터페이스를 모의 구현에 매핑할 수 있습니다.
모노레포에서 import 단순화: 모노레포에서는 paths를 사용하여 다른 패키지 내의 모듈에 매핑할 수 있습니다.

import 경로 관리를 위한 모범 사례

import 경로의 효과적인 관리는 확장 가능하고 유지 관리 가능한 TypeScript 애플리케이션을 구축하는 데 중요합니다. 따르해야 할 몇 가지 모범 사례는 다음과 같습니다.

node 모듈 해석 전략 사용: node 모듈 해석 전략은 일관되고 예측 가능한 모듈 해석 동작을 제공하므로 대부분의 TypeScript 프로젝트에 권장되는 선택입니다.
baseUrl 구성: 소스 코드의 루트 디렉토리에 baseUrl 옵션을 설정하여 import 경로를 단순화하고 가독성을 향상시킵니다.
paths를 사용자 지정 경로 매핑에 사용: paths 옵션을 사용하여 모듈에 대한 별칭을 만들고 import를 다른 위치로 리디렉션하여 import 경로에서 물리적 파일 구조를 추상화합니다.
깊게 중첩된 상대 import 경로 피하기: 깊게 중첩된 상대 import 경로(예: ../../../../utils/helpers)는 읽고 유지 관리하기 어렵습니다. baseUrl 및 paths를 사용하여 이러한 경로를 단순화합니다.
import 스타일에 일관성 유지: 일관된 import 스타일(예: 절대 import 또는 상대 import 사용)을 선택하고 프로젝트 전체에서 이를 따릅니다.
코드를 잘 정의된 모듈로 구성: 코드를 잘 정의된 모듈로 구성하면 이해하고 유지 관리하기가 더 쉬워지며 import 경로 관리 프로세스가 단순화됩니다.
코드 포맷터 및 린터 사용: 코드 포맷터 및 린터는 일관된 코딩 표준을 적용하고 import 경로의 잠재적인 문제를 식별하는 데 도움이 될 수 있습니다.

모듈 해석 문제 해결

모듈 해석 문제는 디버깅하기 까다로울 수 있습니다. 몇 가지 일반적인 문제와 해결 방법은 다음과 같습니다.

"모듈을 찾을 수 없습니다" 오류:
- 문제: TypeScript가 지정된 모듈을 찾을 수 없습니다.
- 해결책:
  - 모듈이 설치되었는지 확인합니다(npm 패키지인 경우).
  - import 경로의 오타를 확인합니다.
  - tsconfig.json에서 moduleResolution, baseUrl 및 paths 옵션이 올바르게 구성되었는지 확인합니다.
  - 모듈 파일이 예상 위치에 있는지 확인합니다.
잘못된 모듈 버전:
- 문제: 호환되지 않는 버전의 모듈을 import하고 있습니다.
- 해결책:
  - package.json 파일을 확인하여 모듈의 어떤 버전이 설치되었는지 확인합니다.
  - 모듈을 호환 가능한 버전으로 업데이트합니다.
순환 종속성:
- 문제: 두 개 이상의 모듈이 서로 의존하여 순환 종속성을 생성합니다.
- 해결책:
  - 순환 종속성을 끊기 위해 코드를 리팩토링합니다.
  - 의존성 주입을 사용하여 모듈을 분리합니다.

다양한 프레임워크에 걸친 실제 예시

TypeScript 모듈 해석의 원칙은 다양한 JavaScript 프레임워크에 적용됩니다. 다음은 일반적인 사용 방법입니다.

React:
- React 프로젝트는 컴포넌트 기반 아키텍처에 크게 의존하므로 올바른 모듈 해석이 중요합니다.
- baseUrl을 src 디렉토리를 가리키도록 사용하면 import MyComponent from 'components/MyComponent';와 같은 깔끔한 import가 가능합니다.
- styled-components 또는 material-ui와 같은 라이브러리는 일반적으로 node 해석 전략을 사용하여 node_modules에서 직접 import됩니다.
Angular:
- Angular CLI는 baseUrl 및 paths를 포함한 합리적인 기본값을 사용하여 tsconfig.json을 자동으로 구성합니다.
- Angular 모듈 및 컴포넌트는 종종 기능 모듈로 구성되며, 모듈 내부 및 간의 import를 단순화하기 위해 경로 별칭을 활용합니다. 예를 들어, @app/shared는 공유 모듈 디렉토리를 가리킬 수 있습니다.
Vue.js:
- React와 유사하게 Vue.js 프로젝트는 baseUrl을 사용하여 컴포넌트 import를 간소화합니다.
- Vuex 저장소 모듈은 paths를 사용하여 쉽게 별칭을 지정할 수 있어 코드베이스의 구성 및 가독성을 향상시킵니다.
Node.js (Express, NestJS):
- NestJS는 예를 들어 구조화된 애플리케이션에서 모듈 import를 관리하기 위해 경로 별칭을 광범위하게 사용하는 것을 권장합니다.
- node 모듈 해석 전략은 기본이며 node_modules와 함께 작업하는 데 필수적입니다.

결론

TypeScript의 모듈 해석 시스템은 코드베이스를 구성하고 종속성을 효과적으로 관리하는 강력한 도구입니다. 다른 모듈 해석 전략, baseUrl 및 paths의 역할, import 경로 관리를 위한 모범 사례를 이해함으로써 확장 가능하고, 유지 관리 가능하며, 읽기 쉬운 TypeScript 애플리케이션을 구축할 수 있습니다. tsconfig.json에서 모듈 해석을 올바르게 구성하면 개발 워크플로우를 크게 개선하고 오류 위험을 줄일 수 있습니다. 다양한 구성을 실험하고 프로젝트 요구 사항에 가장 적합한 접근 방식을 찾으십시오.

TypeScript 모듈 해석: import 경로 전략 해부

모듈 해석이란?

모듈 해석 전략

Classic 모듈 해석

Node 모듈 해석

tsconfig.json에서 모듈 해석 구성

baseUrl 및 paths: import 경로 제어

baseUrl

paths

import 경로 관리를 위한 모범 사례

모듈 해석 문제 해결

다양한 프레임워크에 걸친 실제 예시

결론

`tsconfig.json`에서 모듈 해석 구성

`baseUrl` 및 `paths`: import 경로 제어

`baseUrl`

`paths`