M

MLOG

日本語

TypeScriptのモジュール解決の包括的なガイド。classic、nodeモジュール解決戦略、baseUrl、paths、そして複雑なプロジェクトでのインポートパス管理のベストプラクティスをカバー。

TypeScriptモジュール解決：インポートパス戦略の解明

TypeScriptのモジュール解決システムは、スケーラブルで保守性の高いアプリケーションを構築する上で重要な要素です。 TypeScriptがインポートパスに基づいてモジュールをどのように見つけるかを理解することは、コードベースを整理し、一般的な落とし穴を回避するために不可欠です。 この包括的なガイドでは、TypeScriptモジュール解決の複雑さについて掘り下げ、classicおよびnodeモジュール解決戦略、baseUrlおよびpathsのtsconfig.jsonでの役割、およびインポートパスを効果的に管理するためのベストプラクティスをカバーします。

モジュール解決とは？

モジュール解決とは、TypeScriptコンパイラーが、コード内のインポートステートメントに基づいてモジュールの場所を決定するプロセスです。 import { SomeComponent } from './components/SomeComponent';のように記述すると、TypeScriptは、SomeComponentモジュールが実際にファイルシステム上のどこに存在するかを把握する必要があります。 このプロセスは、TypeScriptがモジュールを検索する方法を定義する一連のルールと構成によって制御されます。

モジュール解決が正しくないと、コンパイルエラー、ランタイムエラーが発生し、プロジェクトの構造を理解することが難しくなる可能性があります。 したがって、モジュール解決をしっかりと理解しておくことは、TypeScript開発者にとって不可欠です。

モジュール解決戦略

TypeScriptには、tsconfig.jsonのmoduleResolutionコンパイラーオプションを介して構成される2つの主要なモジュール解決戦略があります。

Classicモジュール解決

classicモジュール解決戦略は、2つのうちより単純です。 インポート元のファイルからディレクトリツリーを上方向に走査して、モジュールを単純な方法で検索します。

仕組み：

  1. インポート元のファイルを含むディレクトリから開始します。
  2. TypeScriptは、指定された名前と拡張子（.ts、.tsx、.d.ts）を持つファイルを検索します。
  3. 見つからない場合は、親ディレクトリに移動して検索を繰り返します。
  4. このプロセスは、モジュールが見つかるか、ファイルシステムのルートに到達するまで続行されます。

例：

次のプロジェクト構造を考えてみましょう。


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

app.tsにインポートステートメントimport { SomeComponent } from './components/SomeComponent';が含まれている場合、classicモジュール解決戦略は次のようになります。

  1. srcディレクトリで、./components/SomeComponent.ts、./components/SomeComponent.tsx、または./components/SomeComponent.d.tsを検索します。
  2. 見つからない場合は、親ディレクトリ（プロジェクトルート）に移動して検索を繰り返します。この場合、コンポーネントがsrcフォルダー内にあるため、成功する可能性は低いです。

制限事項：

使用する場合：

classicモジュール解決戦略は、ディレクトリ構造が単純で、外部の依存関係がない非常に小規模なプロジェクトにのみ適しています。 現代のTypeScriptプロジェクトは、ほぼ常にnodeモジュール解決戦略を使用する必要があります。

Nodeモジュール解決

nodeモジュール解決戦略は、Node.jsで使用されるモジュール解決アルゴリズムを模倣しています。 これにより、Node.jsをターゲットとするプロジェクトやnpmパッケージを使用するプロジェクトに最適な選択肢となり、一貫性があり予測可能なモジュール解決動作が提供されます。

仕組み：

nodeモジュール解決戦略は、より複雑な一連のルールに従い、node_modules内の検索を優先し、さまざまなファイル拡張子を処理します。

  1. 非相対インポート： インポートパスが./、../、または/で始まらない場合、TypeScriptは、node_modulesにあるモジュールを参照すると仮定します。 次の場所でモジュールを検索します。
    • 現在のディレクトリのnode_modules。
    • 親ディレクトリのnode_modules。
    • ...以下同様に、ファイルシステムのルートまで。
  2. 相対インポート： インポートパスが./、../、または/で始まる場合、TypeScriptはそれを相対パスとして扱い、指定された場所でモジュールを検索し、次を考慮します。
    • 最初に、指定された名前と拡張子（.ts、.tsx、.d.ts）を持つファイルを検索します。
    • 見つからない場合は、指定された名前のディレクトリと、そのディレクトリ内のindex.ts、index.tsx、またはindex.d.tsという名前のファイルを検索します（例：インポートが./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';が含まれている場合、nodeモジュール解決戦略は次のようになります。

  1. lodashが非相対インポートであることを認識します。
  2. プロジェクトルート内のnode_modulesディレクトリでlodashを検索します。
  3. node_modules/lodash/lodash.jsでlodashモジュールを見つけます。

helpers.tsにインポートステートメントimport { SomeHelper } from './SomeHelper';が含まれている場合、nodeモジュール解決戦略は次のようになります。

  1. ./SomeHelperが相対インポートであることを認識します。
  2. src/utilsディレクトリで、./SomeHelper.ts、./SomeHelper.tsx、または./SomeHelper.d.tsを検索します。
  3. これらのファイルがどれも存在しない場合は、SomeHelperという名前のディレクトリを検索し、そのディレクトリ内でindex.ts、index.tsx、またはindex.d.tsを検索します。

利点：

使用する場合：

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：

baseUrlとpaths：インポートパスの制御

baseUrlとpathsのコンパイラーオプションは、TypeScriptがインポートパスを解決する方法を制御するための強力なメカニズムを提供します。 絶対インポートを使用し、カスタムパス・マッピングを作成できるようにすることで、コードの可読性と保守性を大幅に向上させることができます。

baseUrl

baseUrlオプションは、非相対モジュール名の解決のベースディレクトリを指定します。 baseUrlが設定されている場合、TypeScriptは、現在の作業ディレクトリではなく、指定されたベースディレクトリを基準にして非相対インポートパスを解決します。

例：

次のプロジェクト構造を考えてみましょう。


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

tsconfig.jsonに次が含まれている場合：


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

次に、app.tsでは、次のインポートステートメントを使用できます。


import { SomeComponent } from 'components/SomeComponent';

代わりに：


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

TypeScriptは、baseUrlで指定された./srcディレクトリを基準にしてcomponents/SomeComponentを解決します。

baseUrlを使用するメリット：

paths

pathsオプションを使用すると、モジュールのカスタムパス・マッピングを構成できます。 TypeScriptがインポートパスを解決する方法を制御するための、より柔軟で強力な方法を提供し、モジュールのエイリアスを作成し、インポートを別の場所にリダイレクトできます。

pathsオプションは、各キーがパスパターンを表し、各値がパス置換の配列であるオブジェクトです。 TypeScriptは、インポートパスをパスパターンと照合しようとし、一致が見つかった場合は、インポートパスを指定された置換パスに置き換えます。

例：

次のプロジェクト構造を考えてみましょう。


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 { SomeComponent } from '@components/SomeComponent';
import { MyLibraryFunction } from '@mylib';

TypeScriptは、@components/SomeComponentを@components/*パス・マッピングに基づいてcomponents/SomeComponentに解決し、@mylibを@mylibパス・マッピングに基づいて../libs/my-library.tsに解決します。

pathsを使用するメリット：

pathsの一般的な使用例：

インポートパスを管理するためのベストプラクティス

インポートパスの効率的な管理は、スケーラブルで保守性の高いTypeScriptアプリケーションを構築するために不可欠です。 従うべきベストプラクティスを次に示します。

モジュール解決の問題のトラブルシューティング

モジュール解決の問題は、デバッグするのが面倒な場合があります。 一般的な問題とその解決策を次に示します。

さまざまなフレームワークでの実際の例

TypeScriptモジュール解決の原則は、さまざまなJavaScriptフレームワークに適用されます。 一般的な使用方法を次に示します。

結論

TypeScriptのモジュール解決システムは、コードベースを整理し、依存関係を効果的に管理するための強力なツールです。 さまざまなモジュール解決戦略、baseUrlとpathsの役割、およびインポートパスを管理するためのベストプラクティスを理解することにより、スケーラブルで、保守性が高く、読みやすいTypeScriptアプリケーションを構築できます。 tsconfig.jsonでモジュール解決を適切に構成すると、開発ワークフローが大幅に改善され、エラーのリスクが軽減されます。 さまざまな構成を試して、プロジェクトのニーズに最適なアプローチを見つけてください。