モジュール解決
このセクションは、基本的なモジュールの知識があることを前提にしています。 詳しい情報については、モジュールのドキュメントを参照してください。
- 相対(Relative) vs 非相対(Non-relative)モジュールimport
- モジュール解決の方針
- 拡張モジュール解決フラグ
- モジュール解決のトレース
- --noResolveの使用
- よくある質問
モジュール解決は、import
が何を参照するのかを把握するために、コンパイラを利用するプロセスになります。
import { a } from "moduleA";
のようなimport
文について考えてみてください。
a
の使用するために、コンパイラは正確に何が提供されているのかを知る必要があり、
またmoduleA
の定義を調べる必要もあります。
ここで、コンパイラは"moduleA
はどのような形状をしていますか?"と尋ねます。
これは一見単純なように見えますが、コードによってmoduleA
は.ts
/.tsx
ファイル、
または.d.ts
ファイルのいずれかに定義されることになります。
まず、コンパイラはimportされているモジュールのファイルを見つけようとします。
これを行うには、コンパイラは2つの異なる方針、クラシックまたはNodeのどちらかに従います。
これらの方針が、moduleA
を探す場所をコンパイラに教えます。
これが動かなかった場合、モジュール名に相対関係が無かった場合(ここでは"moduleA")、 コンパイラはambientモジュール宣言を見つけようとします。 この次に、非相対のimportについて説明します。
最終的にコンパイラがモジュールの解決が出来なかった場合、エラーログを出力します。
このケースでは、error TS2307: Cannot find module 'moduleA'
のようなエラーが出力されます。
相対(Relative) vs 非相対(Non-relative)モジュールimport
モジュールのimportは、モジュール参照が相対か非相対のどちらかをもとに異なる解決がされます。
相対importは、/
、./
、または../
のいずれかから始まります。
下記に幾つかの例を示します。
import Entry from "./components/Entry";
import { DefaultHeaders } from "../constants/http";
import "/mod";
これ以外のimportは非相対とみなされます。下記に幾つかの例を示します。
import * as $ from "jquery";
import { Component } from "angular2/core";
相対importは、importするファイルを相対関係によって解決し、ambientモジュール宣言を相対関係で解決することはできません。 自身が開発した実行時に相対関係の保持が保証されるモジュールに対しては、 相対importを使用するべきです。
非相対importは、baseUrl
の相対、またはパスのマッピングを通して解決され、
これについては後ほど説明します。
これらは、ambientモジュール宣言の解決も行います。
外部に依存関係を持つものをインポートする際は、非相対パスを使用してください。
モジュール解決の方針
モジュール解決の方針には、Nodeとクラシックの2つが存在します。
--moduleResolution
を使用して、モジュール解決の方針を指定することが可能です。
指定されない場合、デフォルトはNodeになります。
クラシック
これは、TypeScriptのデフォルトの解決の方針として使用されます。 最近では、主にこの方針が後方互換のために提供されています。
相対importはインポートするファイルを相対的に解決します。
そのため、ソースファイルである/root/src/folder/A.ts
内のimport { b } from "./moduleB"
は、
次のようにファイルを探します。
/root/src/folder/moduleB.ts
/root/src/folder/moduleB.d.ts
非相対モジュールのインポートに対しては、コンパイラはimportするファイルを含むディレクトリを出発点としてディレクトリツリーを巡り、 目的の定義ファイルを見つけ出そうとします。
例えば、
ソースファイル/root/src/folder/A.ts
内でimport { b } from "moduleB"
のように、
非相対的にmoduleBをインポートする場合は、"moduleB"
を探すために次のような検索が行われます。
/root/src/folder/moduleB.ts
/root/src/folder/moduleB.d.ts
/root/src/moduleB.ts
/root/src/moduleB.d.ts
/root/moduleB.ts
/root/moduleB.d.ts
/moduleB.ts
/moduleB.d.ts
Node
この解決方針は、実行時のNode.jsのモジュール解決のメカニズムを真似ることを試みたものです。 完全なNode.jsの解決アルゴリズムは、 Node.jsのモジュールのドキュメントに概要が説明されています。
Node.jsのモジュール解決の方法
TSコンパイラがどのような手順を踏んでいるのかを理解するには、
Node.jsモジュールにスポットライトを当てることが重要です。
伝統的に、Node.js内でのimoportはrequire
という名前の関数を呼び出すことで実行されます。
Node.jsでの動きは、require
が相対パスまたは非相対パスのどちらが与えられているかで、挙動が異なります。
相対パスは、かなり分かりやすいものです。
例として、import var x = require("./moduleB");
を含む/root/src/moduleA.js
にファイルが配置されていたとして、
Node.jsは次の順番でimportの解決を図ります。
- 存在すれば、ファイル名
/root/src/moduleB.js
として解決します。 -
package.json
という名前の"main"
モジュールを指定するファイルが含まれていれば、/root/src/moduleB
フォルダとして解決します。この例であれば、Node.jsは
{ "main": "lib/mainModule.js" }
を含む/root/src/moduleB/package.json
を見つけ、/root/src/moduleB/lib/mainModule.js
を参照します。 -
index.js
という名前のファイルを含んでいれば、/root/src/moduleB
のフォルダとして解決します。 このファイルは暗黙的に、フォルダの"main"
モジュールとみなされます。
この詳細については、 Node.jsのドキュメントのファイルモジュールとフォルダモジュールを参照してください。
ただし、非相対モジュールの名前解決は異なる動きをします。
Nodeはnode_modules
という名前の特別な名前のフォルダ内から、モジュールを探します。
node_modules
フォルダは現在のファイルの同階層、またはディレクトリのチェーン上の上層に配置することが可能です。
Nodeはディレクトリチェーンを巡り、読み込もうとしているモジュールを見つけるまで、各node_modules
を探します。
前述の例を、仮に/root/src/moduleA.js
が非相対パスを使用するとして、
var x = require("moduleB");
のimport指定があったとしましょう。
NodeはmoduleB
の解決を、それが成功するまで各場所で試みます。
/root/src/node_modules/moduleB.js
/root/src/node_modules/moduleB/package.json
("main"
指定があれば)/root/src/node_modules/moduleB/index.js
/root/node_modules/moduleB.js
/root/node_modules/moduleB/package.json
("main"
指定があれば)/root/node_modules/moduleB/index.js
/node_modules/moduleB.js
/node_modules/moduleB/package.json
("main"
指定があれば)/node_modules/moduleB/index.js
Node.jsがディレクトリを(4)と(7)で遡っていることに注目してください。
このプロセスの詳細については、Node.jsのドキュメントのnode_modulesからのモジュール読み込みで読むことができます。
TypeScriptのモジュール解決方法
TypeScriptはコンパイル時にモジュールのための定義ファイルを探すために、Node.jsのランタイム時の解決方針を真似します。 これを実現するために、TypeScriptはNodeの解決ロジックに対して、TypeScriptのソースファイル拡張子(.ts、.tsx、.d.ts)を覆い被せます。
また、TypeScriptはpackage.json
内の"typings"
と名付けられたフィールドを、
"main"
の意図を映すのにも使用します。
コンパイラはこれを"main"
定義ファイルを見つけるために使用します。
例えば、/root/src/moduleA.ts
内のimport { b } from "./moduleB"
のようなimport文は、
結果的に"./moduleB"
を、次のように探すことを試みます。
/root/src/moduleB.ts
/root/src/moduleB.tsx
/root/src/moduleB.d.ts
/root/src/moduleB/package.json
("typings"があれば)/root/src/moduleB/index.ts
/root/src/moduleB/index.tsx
/root/src/moduleB/index.d.ts
Node.jsのことを振り返ってみると、moduleB.js
という名前のファイルを探し、
次に該当するpackage.json
を、その次にindex.js
を探していました。
同様に非相対importはNode.jsの解決ロジックに従い、まずファイルを探し、次に該当するフォルダを探します。
そのため、ソースファイル/root/src/moduleA.ts
内のimport { b } from "moduleB"
は、
結果的に次の順番で検索します。
/root/src/node_modules/moduleB.ts
/root/src/node_modules/moduleB.tsx
/root/src/node_modules/moduleB.d.ts
/root/src/node_modules/moduleB/package.json
("typings"があれば)/root/src/node_modules/moduleB/index.ts
/root/src/node_modules/moduleB/index.tsx
/root/src/node_modules/moduleB/index.d.ts
/root/node_modules/moduleB.ts
/root/node_modules/moduleB.tsx
/root/node_modules/moduleB.d.ts
/root/node_modules/moduleB/package.json
("typings"があれば)/root/node_modules/moduleB/index.ts
/root/node_modules/moduleB/index.tsx
/root/node_modules/moduleB/index.d.ts
/node_modules/moduleB.ts
/node_modules/moduleB.tsx
/node_modules/moduleB.d.ts
/node_modules/moduleB/package.json
("typings"があれば)/node_modules/moduleB/index.ts
/node_modules/moduleB/index.tsx
/node_modules/moduleB/index.d.ts
このステップ数に怯えることはありません。 TypeScriptは相変わらず(8)と(15)で2度ディレクトリを遡っているにすぎません。 これはNode.js自身が行っている以上の複雑さはありません。
拡張モジュール解決フラグ
プロジェクトのソースファイルの配置は、時に出力の配置と一致しないことがあります。 通常であればビルド結果は、最終的な出力を生成する結果となります。
これらは、.ts
ファイルを.js
ファイルにコンパイルし、
依存性を異なるソースの複数の配置場所から単一の出力場所にコピーすることを含みます。
その結果、ランタイム時のモジュールは、それらの定義を含むソースファイルのものとは異なる名前になる可能性があります。
また、最終的な出力のモジュールのパスは、コンパイル時のソース・ファイルのパスに対応したものと一致しない可能性があります。
TypeScriptのコンパイラには、最終的な出力の生成で期待されるされることを、 変換時にコンパイラに伝えるための追加のフラグが用意されています。
コンパイラはこれらの変換のいずれかを実行しないことに注意しなければいけません。 これらの情報の一部分を、定義ファイルのimportによるモジュール解決の指針として使用しているに過ぎません。
Base URL
baseUrl
の使用は、モジュールがランタイム時に単一のフォルダに"配置(deployed)"されている状況で、
AMDモジュールローダーを使用するアプリケーションの慣習となっています。
これらモジュールのソースファイルは異なるディレクトリに配置することが可能ですが、
ビルドスクリプトで全てまとめられます。
baseUrl
を設定することで、コンパイラにモジュールを探す場所を伝えます。
非相対の全てのモジュールのimportは、baseUrl
への相対とみなされます。
baseUrl
の値は下記のいずれかによって決定されます。
-
コマンドライン引数
baseUrl
の値 (指定されたパスが相対の場合、現在のディレクトリが基準となります) -
'tsconfig.json'
内のbaseUrl
プロパティの値 (指定されたパスが相対の場合、'tsconfig.json'
が配置されている場所が基準となります)
相対モジュールのimportは常にimportするファイルが相対的に解決されるため、
baseUrl
の設定による影響を受けないことに注意してください。
詳細については、 RequireJSと、 SystemJSのドキュメントを参照してください。
パス・マッピング
場合によって、モジュールがbaseUrl
下に直接配置されないことがあります。
例えば、"jquery"
モジュールのimportは、実行時には"node_modules\jquery\dist\jquery.slim.min.js"
に変換されます。
ローダーは実行時にモジュール名をファイルに紐付けるマッピング設定を使用します。
詳細については、RequireJsのドキュメントと、
SystemJSのドキュメントを参照してください。
TypeScriptのコンパイラは、このようなマッピングの宣言をtsconfig.json
ファイル内の"paths"
プロパティによってサポートします。
下記は、jQueryのために"paths"
プロパティを指定する例になります。
{
"compilerOptions": {
"paths": {
"jquery": ["node_modules/jquery/dist/jquery.d.ts"]
}
}
"paths"を使用すると、複数のフォールバック位置を含む、より洗練されたマッピングも可能になります。 1つの場所でいくつかのモジュールしか利用できず、残りのモジュールが別の場所にあるプロジェクト構成があるとすると、 ビルドステップで、全てが1つの場所にまとめられます。 プロジェクトのレイアウトが、下記の構成だとすると、
projectRoot
├── folder1
│ ├── file1.ts (imports 'folder1/file2' and 'folder2/file3')
│ └── file2.ts
├── generated
│ ├── folder1
│ └── folder2
│ └── file3.ts
└── tsconfig.json
対応するtsconfig.json
はこのようになります。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"*": [
"*",
"generated/*"
]
}
}
}
これは、パターン "*"(すなわち、すべての値)と一致するモジュールのインポートをコンパイラに指示し、2つの場所を検索します。
-
"*"
: 同じ名前で変更されないことを意味し、次のようにマップします。<moduleName>
=><baseUrl>
\<moduleName>
-
"generated\*"
は接頭辞として"generated"
をモジュール名の前に付けるため、次のようにマップします。<moduleName>
=><baseUrl>
\generated\<moduleName>
このロジックに従い、コンパイラは次のようにして2つのインポートの解決を試みます。
- import 'folder1/file2'
- パターン'*'がマッチし、ワイルドカードは全モジュール名を取得します。
-
1つ目の置換を試みます: '*' ->
folder1/file2
-
置換の結果をbaseUrlを連結して相対的な名前にします: ->
projectRoot/folder1/file2.ts
- このファイルが存在するので、完了となります。
- import 'folder2/file3'
- パターン'*'がマッチし、ワイルドカードは全モジュール名を取得します。
-
1つ目の置換を試みます:
'*'
->folder2/file3
-
置換の結果をbaseUrlを連結して相対的な名前にします: ->
projectRoot/folder2/file3.ts
- ファイルが存在しないため、2つ目の置換処理に移行します。
-
2つ目の置換: 'generated/*' ->
generated/folder2/file3
-
置換の結果をbaseUrlを連結して相対的な名前にします: ->
projectRoot/generated/folder2/file3.ts
- このファイルが存在するので、完了となります。
rootDirを使用した仮想ディレクトリ
時折、コンパイル時に複数のディレクトリから構成されるプロジェクトのソースが、 1つの出力ディレクトリに生成されるために、全てが結合されることがあります。 この場合、ソースのディレクトリの集まりとして"仮想"ディレクトリとしてみなすことができます。
'rootDirs'を使用することで、この"仮想"ディレクトリを構成するrootをコンパイラに伝えることができます。 コンパイラは、これらの「仮想」ディレクトリ内の相対モジュールのインポートを、 1つのディレクトリにまとめてマージしたかのように解決することができます。
例えば、次のようなプロジェクト構成があるとします。
src
└── views
└── view1.ts (imports './template1')
└── view2.ts
generated
└── templates
└── views
└── template1.ts (imports './view2')
src/views
のファイルは幾つかのUI制御のためのユーザーコードです。
generated/templates
のファイルは、
ビルドの一部としてテンプレートのジェネレーターによって自動生成されるコードに紐づくUIテンプレートです。
ビルドの段階で、/src/views
と/generated/templates/views
のファイルがコピーされ、同じディレクトリに出力されます。
実行時には、viewはそのテンプレートが同ディレクトリ内に存在すると期待するため、
相対名"./template"
を使用してimportしようとするでしょう。
この関係性をコンパイラに伝えるために、"rootDirs"
を使用します。
"rootDirs"
には、実行時にマージされることが期待されるコンテンツのルートのリストを指定します。
先程の例であれば、tsconfig.json
ファイルは次のようになります。
{
"compilerOptions": {
"rootDirs": [
"src/views",
"generated/templates/views"
]
}
}
コンパイラはrootDirs
の各サブフォルダ内のモジュールの相対インポートを見つける度に、
rootDirs
の各エントリでこのインポートを探そうとします。
モジュール解決のトレース
前述したように、コンパイラはモジュールを解決する際に、現在のフォルダの外にあるファイルを参照することができます。
これはモジュールが解決されなかった理由を診断するときや、誤った定義で解決されようとしたときには厳しい場合があります。
--traceResolution
を使用してコンパイラによるモジュール解決のトレースを有効にすると、
モジュール解決プロセス中に何が起こったかがわかります。
typescript
モジュールを使用するサンプルアプリケーションがあり、
app.ts
にはimport * as ts from "typescript"
のインポートがあるとします。
│ tsconfig.json
├───node_modules
│ └───typescript
│ └───lib
│ typescript.d.ts
└───src
app.ts
--traceResolution
を使用してコンパイラを実行します。
tsc --traceResolution
出力される結果は次のようになります。
======== Resolving module 'typescript' from 'src/app.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'typescript' from 'node_modules' folder.
File 'src/node_modules/typescript.ts' does not exist.
File 'src/node_modules/typescript.tsx' does not exist.
File 'src/node_modules/typescript.d.ts' does not exist.
File 'src/node_modules/typescript/package.json' does not exist.
File 'node_modules/typescript.ts' does not exist.
File 'node_modules/typescript.tsx' does not exist.
File 'node_modules/typescript.d.ts' does not exist.
Found 'package.json' at 'node_modules/typescript/package.json'.
'package.json' has 'typings' field './lib/typescript.d.ts' that references 'node_modules/typescript/lib/typescript.d.ts'.
File 'node_modules/typescript/lib/typescript.d.ts' exist - use it as a module resolution result.
======== Module name 'typescript' was successfully resolved to 'node_modules/typescript/lib/typescript.d.ts'. ========
各行の説明
-
名前とインポート場所
======== Resolving module 'typescript' from 'src/app.ts'. ========
-
コンパイラが従う戦略
Module resolution kind is not specified, using 'NodeJs'.
-
npmパッケージからのtypingsの読み込み
'package.json' has 'typings' field './lib/typescript.d.ts' that references 'node_modules/typescript/lib/typescript.d.ts'.
-
最終的な結果
======== Module name 'typescript' was successfully resolved to 'node_modules/typescript/lib/typescript.d.ts'. ========
--noResolveの使用
通常コンパイラは、コンパイル処理が開始される前に、全てのモジュールインポートを解決しようと試みます。 インポートするファイルの解決に成功すると、そのファイルはコンパイラが後で処理をするファイルの集まりに加えられます。
--noResolve
コンパイラオプションは、コンパイラで渡されなかったファイルを、
コンパイルに"追加"しないようにコンパイラに指示します。
それでもモジュールのファイルを解決しようとしますが、指定されていないファイルが含まれることはありません。
例えば、
app.ts
import * as A from "moduleA" // OK, 'moduleA' passed on the command-line
import * as B from "moduleB" // Error TS2307: Cannot find module 'moduleB'.
tsc app.ts moduleA.ts --noResolve
--noResolve
を使用したapp.ts
のコンパイルの結果は次のようになるはずです。
-
コマンドラインで渡されたとして、
moduleA
は正しく検索されます。 -
コマンドラインで渡されなかったので、
moduleB
の検索はエラーになります。
よくある質問
何故、除外(exclude)リストのモジュールがコンパイラによって引き上げられるのですか?
tsconfig.json
はフォルダを"プロジェクト"に変換します。
"exclude"または"files"が指定されていないものは、
tsconfig.json
を含む全てのフォルダとそのサブフォルダ内のファイルがコンパイルに含まれることになります。
もし、"exclude"を使用して特定のファイルを除外したい場合でも、 コンパイラに全てのファイルを参照させる代わりに、"files"を使用して全てのファイルを指定するのがよいかもしれません。(翻訳に自信なし)
© https://github.com/Microsoft/TypeScript-Handbook
このページは、ページトップのリンク先のTypeScript-Handbook内のページを翻訳した内容を基に構成されています。 下記の項目を確認し、必要に応じて公式のドキュメントをご確認ください。 もし、誤訳などの間違いを見つけましたら、 @tomofまで教えていただければ幸いです。
- ドキュメントの情報が古い可能性があります。
- "訳注:"などの断わりを入れた上で、日本人向けの情報やより分かり易くするための追記を行っている事があります。