TypeScript の使い方

npm を使ってインストールするには、下記のコマンドを実行するだけです。 基本的には開発環境で使うツールだと思いますので、--save-dev オプションを付けておきましょう。 npm の使い方がわからないという方は、まずは「Node.js と npm の使い方（その１：概要）」を参考にしてください。

npm install --save-dev typescript

TypeScript をインストールすると、tsc コマンドが使えるようになっています。 下記のコマンドを実行してバージョン番号が表示されれば、ちゃんとインストールできています。

ちなみに "tsc" という名前は、"TypeScript Compiler" の略のようです。

なお、コマンドは "./node_modules/.bin" にインストールされます。 コマンドが見つからない場合は、"./node_modules/.bin" に PATH を通しておくか、 相対パスで "./node_modules/.bin/tsc" と指定するか、 もしくは npx コマンドを使用するなどの対応を行ってください。 この記事では、説明の簡略化のために "./node_modules/.bin" に PATH を通してあることを前提として説明していきます。

tsc --version

tsc コマンドの詳しい使い方が知りたい場合は、ヘルプを表示してみましょう。

tsc --help

特定のファイルのみを変換する場合は、tsc コマンドの後にファイル名を指定します。 なお、この方法を使用すると TypeScript の設定ファイルが無視されるので注意してください。

tsc ./src/hoge.ts

tsc ./src/*.ts ./tests/*.ts

tsc コマンドをオプション無しで実行すると、設定ファイルの内容に従って変換処理が実行されます。 設定ファイルが無い場合は、ヘルプが表示されます。 設定ファイルの作り方については後述します。

tsc

ファイルを変更するたびに変換処理を実行する必要があるわけですが、毎回毎回ファイルを変更するたびに変換処理を実行するのはとても面倒です。 そこで、ファイルの変更を tsc が監視し、ファイルに変更があった場合に自動で変換処理を実行してくれるようになるオプション --watch があります。 このオプションを付けて tsc コマンドを実行すると、そのファイルに何か変更があった場合、自動で変換処理が実行されるようになります。 監視をやめる場合は、Ctrl + C を押せば終了できます。

tsc --watch

TypeScript のデフォルトの設定ファイル「tsconfig.json」は、 手動で作成することもできますが、自動で作成してくれる機能がありますので、まずはこれを利用しましょう。 自動で作成するには、tsc コマンドに --init オプションを付けて実行します。

tsc --init

設定ファイルを使用する方法は2つあります。

tsc

tsc -p config.json

どんな設定項目があるかは、ここでは記載しません。 大量にありますので、公式のドキュメントを見てもらった方が良いと思います。

• TypeScript: TSConfig リファレンス - すべてのTSConfigのオプションのドキュメント

ここでは簡単な例だけ記載しておきます。

{
	"compilerOptions": {

		// 動作させたい環境
		"target": "es2016",

		// モジュールの出力形式
		"module": "esnext",

		// 変換元のディレクトリ
		"rootDir": "./assets/js/",

		// ソースマップを出力するか
		"sourceMap": true,

		// 出力先のディレクトリ
		"outDir": "./public/js/",

		// CommonJS と ES Modules で相互利用するか
		"esModuleInterop": true,

		// ファイル名の大文字小文字を区別するか
		"forceConsistentCasingInFileNames": true,

		// 厳密チェックするか
		"strict": true,

		// 型を指定していない場合にエラーにするか
		"noImplicitAny": true,

		// 型定義ファイル（".d.ts"）のチェックをスキップするか
		"skipLibCheck": true
	}
}

パッと思いつく単純な方法は tsc コマンドを実行し、 そのあとに webpack コマンドを実行することです。 一見すると特に問題はないように感じてしまいますが、実はこの方法にはいくつか問題があります。

tsc && webpack

上記のように tsc コマンドと webpack コマンドを別々に呼んでしまうと、 ソースマップファイルがそれぞれのコマンドで別々に出力されてしまい、 ブラウザが読み込んだソースマップファイルから ".ts" ファイルまで到達しないという問題が発生します。 tsc コマンドが ".ts" ファイルから ".js"（圧縮前）ファイルへのソースマップを出力し、 webpack コマンドが ".js"（圧縮前）ファイルから ".js"（圧縮後）ファイルへのソースマップを出力します。 ブラウザは webpack コマンドが出力したソースマップを読み込むことになりますから、 ".js"（圧縮前）ファイルまでしか到達できないのです。 また、".js"（圧縮前）ファイルは作業用の中間ファイルとしてしか使用されませんから、 それらのファイルがゴミとして邪魔になってしまいます（デバッグする際には逆に便利なのかもしれませんが）。

ではどうすれば良いのかというと、tsc コマンドを使用せずに、 全部まとめて webpack コマンドで処理させれば良いのです。 つまり、webpack が ".ts" ファイルを読み込めるようなれば良いのです。 そうすれば、webpack が出力するソースマップが ".ts" ファイルまで到達するようになります。 とはいえ、デフォルトの webpack では ".ts" ファイルを扱えません。 そこで、webpack で ".ts" ファイルを扱えるようにするために、ts-loader を使用します。

• GitHub - TypeStrong/ts-loader: TypeScript loader for webpack

ts-loader をインストールするには、下記のコマンドを実行します。

npm install --save-dev ts-loader

ts-loader パッケージがインストールできたら、webpack の設定ファイルで、".ts" ファイルを読み込めるように変更します。 下記の例を見てください。 この例は、"./src/index.ts" ファイルを変換し、"./dist/main.js" ファイルに、圧縮（minify）して出力するという設定になります。 変換前のファイル（entry）が、".js" ではなく ".ts" ファイルになっていることに注目してください。

module.exports = {
	mode: 'production',
	entry: {
		main: './src/index.ts'
	},
	output: {
		path: __dirname + '/dist',
		filename: '[name].js'
	},
	module: {
		rules: [
			{
				test: /\.ts$/,
				loader: 'ts-loader'
			}
		]
	}
};

モジュールを TypeScript で作成した場合、そのファイルの拡張子は ".ts" になると思いますが、 そのファイルを import で読み込む際に、拡張子を ".ts" と指定するとエラーになってしまいます。

// import で拡張子 ".ts" はエラーになる
import hello from '../assets/js/modules/hello.ts';

An import path can only end with a '.ts' extension when 'allowImportingTsExtensions' is enabled.

実はこれはかなり厄介な問題でして、TypeScript 5.0 で allowImportingTsExtensions オプションが追加されるなどの対応が行われましたが、 ts-loader などはまだ完全には対応できていないようです。

• TypeScript: Documentation - TypeScript 5.0
• ts-loader doesn't work when ts-config noEmit is set to true · Issue #1602 · TypeStrong/ts-loader · GitHub

現状での解決策としては、import のパスには拡張子を指定せずに、 webpack で拡張子を ".ts" に補完させるのがベターな気がします。 設定するには、webpack の設定ファイルの resolve 項目の extensions で ".ts" を指定します。 なお、extensions で '...' と指定すると、デフォルトの拡張子を指定していることと同じ意味になります。

// import で拡張子は指定しない
import hello from '../assets/js/modules/hello';

module.exports = {
	mode: 'production',
	entry: {
		main: './src/index.ts'
	},
	output: {
		path: __dirname + '/dist',
		filename: '[name].js'
	},
	resolve: {
		extensions: ['.ts', '...']
	},
	module: {
		rules: [
			{
				test: /\.ts$/,
				loader: 'ts-loader'
			}
		]
	}
};

typescript-eslint をインストールするには、下記のコマンドを実行します。 「@typescript-eslint/parser」パッケージと、「@typescript-eslint/eslint-plugin」パッケージの2つが必要になるので注意してください。

npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

typescript-eslint がインストールできたら、ESLint の設定ファイルで、".ts" ファイルを読み込めるよう、下記のように変更します。 やっている内容としては、TypeScript をパースするために「@typescript-eslint/parser」パッケージを使用し、 TypeScript 用のコーディング規約を使用するために「@typescript-eslint/eslint-plugin」パッケージを使用しているといった感じになっています。

module.exports = {
	extends: [
		'eslint:recommended',
		'plugin:@typescript-eslint/recommended'
	],
	parser: '@typescript-eslint/parser',
	plugins: [
		'@typescript-eslint'
	]
};

ts-jest をインストールするには、下記のコマンドを実行します。 「ts-jest」パッケージと、「@types/jest」パッケージの2つが必要になるので注意してください。

npm install --save-dev ts-jest @types/jest

ts-jest がインストールできたら、Jest の設定ファイルで、".ts" ファイルを読み込めるように変更します。

module.exports = {
	preset: "ts-jest"
};

Jest では、設定ファイルの moduleNameMapper 項目で、 モジュールを読み込む際のパスを正規表現で変換することができました。 パスに相対パスを使用してしまうと、階層が深くなった場合に "../" だらけになったり、 各ファイルで指定するパスの階層が異なったりしてメンテナンスが大変になります。

// 階層が深いとパスが "../" だらけになる
import hello from '../../../../../assets/js/modules/hello';

もし、Jest でこの機能を使用してパスを変換しているのであれば、 TypeScript でも同様にパスの変換をしてあげる必要があります。 例えば、パスの指定が / から始まる場合に、 そのパスをアプリケーションのルートディレクトリからの絶対パスとして変換したい場合は、 下記のような設定になります。

module.exports = {
	preset: "ts-jest",
	moduleNameMapper: {
		"^/(.*)$": "<rootDir>/$1"
	}
};

{
	"baseUrl": "./",
	"paths": {
		"/*": ["*"]
	}
}

// 変換後はどの階層からでもこう書ける
import hello from '/assets/js/modules/hello';