TypeScriptの手順でよく見る`npx tsc`。短いコマンドですが、「npxとtscはそれぞれ何をしている？」「グローバルにTypeScriptを入れる必要はある？」「tsconfig.jsonはいつ読まれる？」まで説明しようとすると意外と曖昧になりがちです。結論から言うと、npxはnpmパッケージの実行環境を用意し、tscはTypeScript Compilerを実行します。プロジェクトにTypeScriptをローカル依存として入れ、`npx tsc`でそのコンパイラを使うのが理解しやすい運用です。
まず結論：npxは実行役、tscはコンパイラ
| 名前 | 役割 | 例 |
|---|---|---|
| npx | npmパッケージが提供するコマンドを実行する | `npx tsc` |
| tsc | TypeScriptソースを型チェック・コンパイルするCLI | `tsc –noEmit` |
| tsconfig.json | TypeScript Projectの対象ファイルとCompiler設定を定義する | `compilerOptions`, `include`, `exclude` |
npmの現行ドキュメントでは、npxはnpm execを利用するコマンドとして扱われます。ローカルにインストールされているパッケージの実行ファイルは実行時のPATHへ追加されるため、プロジェクトに`typescript`が入っていれば、その`tsc`を直接パス指定せず呼び出せます。
用語解説：tsc
TypeScript CompilerのCLIです。TypeScriptコードの型チェックを行い、設定に応じてJavaScriptや型定義ファイルなどを出力します。
まずはローカルにTypeScriptを入れる
チーム開発では、各自のPCに異なるグローバル版を入れるより、ProjectのdevDependencyとしてTypeScriptを固定しておく方がバージョンを揃えやすくなります。
npm install --save-dev typescript
npx tsc --versionこの状態なら`npx tsc`はローカルProjectの実行環境から`tsc`を呼び出せます。ローカルに対象packageがない場合、npm exec/npxは条件に応じて取得・実行を提案することがあります。誤ったpackage名を実行しないためにも、Projectへ`typescript`を明示的に追加してから使う方が再現しやすいです。
npx tscだけならtsconfig.jsonを探す
TypeScript公式ドキュメントでは、入力ファイルを指定せず`tsc`を実行すると、現在のディレクトリから親ディレクトリ方向へ`tsconfig.json`を探し、そのProject設定でコンパイルします。npx経由でも実行される本体はtscなので、この挙動は同じです。
npx tsc`tsconfig.json`には、コンパイル対象や`target`、`module`、`strict`、`outDir`などのCompiler設定を書けます。まずProjectの設定を正しく作り、その設定を基準に`npx tsc`を実行するのが基本です。
注意：ファイル名を直接渡すとtsconfigは無視される
実務で特にハマりやすいのがここです。TypeScript公式では、CLIに入力ファイルを指定した場合、`tsconfig.json`は無視されると明記されています。
npx tsc src/index.tsこのコマンドは「Project設定でindex.tsだけをコンパイル」ではありません。CLIで渡したファイルをCompilerのデフォルト設定や同時指定したオプションで処理します。Projectの`strict`や`paths`などを使うつもりなら、単純なファイル指定へ切り替えない方が安全です。
| 目的 | コマンド |
|---|---|
| 現在のtsconfigでProject全体を確認 | `npx tsc` |
| 別の設定ファイルを使う | `npx tsc -p tsconfig.build.json` |
| 特定ファイルをCLI設定で処理 | `npx tsc src/index.ts` |
–projectで使う設定を明示する
複数のtsconfigを使い分けるProjectでは、`–project`または`-p`で設定ファイルや設定ディレクトリを明示できます。
npx tsc --project tsconfig.build.json
# 短縮形
npx tsc -p tsconfig.build.jsonfrontend、test、buildなどで設定が分かれている場合は、実行するConfigを明示すると「どのtsconfigが使われたか」を追いやすくなります。
型チェックだけなら–noEmitを使う
JavaScriptの出力はBundlerに任せ、TypeScriptには型チェックだけさせたいProjectもあります。その場合は`–noEmit`が便利です。
npx tsc --noEmitCIやPull Request前のチェックに組み込む場合も、生成物を必要としないなら`–noEmit`を使うと役割が明確になります。Project側で`noEmit: true`を設定しておく方法もあります。
開発中は–watchで変更を監視する
`–watch`を付けると、TypeScript Compilerが対象ファイルを監視し、変更時に再チェック・再コンパイルします。
npx tsc --watch大規模Projectや特定OS・ファイルシステムで監視負荷が気になる場合は、`tsconfig.json`の`watchOptions`で監視方式を調整できます。通常はまずデフォルトで使い、問題が起きたときに設定を見直します。
package.json scriptsに固定するとチームで揃う
同じコマンドを繰り返すなら、毎回npxのオプションを入力するより`package.json`のscriptsへ名前を付けると、CIとローカルの実行方法を揃えやすくなります。
{
"scripts": {
"typecheck": "tsc --noEmit",
"build:types": "tsc -p tsconfig.build.json",
"typecheck:watch": "tsc --noEmit --watch"
}
}npm run typecheck
npm run build:typesnpm scriptsではProjectのローカル実行ファイルが利用できるため、scripts内で毎回`npx`を書く必要はありません。
困ったときに使える確認コマンド
| 確認したいこと | コマンド |
|---|---|
| 使用しているTypeScript版 | `npx tsc –version` |
| 実際に解決されたCompiler設定 | `npx tsc –showConfig` |
| 別tsconfigの解決結果 | `npx tsc -p tsconfig.build.json –showConfig` |
| 型チェックのみ | `npx tsc –noEmit` |
| 変更監視 | `npx tsc –watch` |
特に「設定したはずのCompiler optionが効かない」ときは、ファイルをCLIへ直接渡していないか確認し、`–showConfig`で実際の設定を表示すると切り分けしやすくなります。
よくある質問
npx tscは毎回TypeScriptをダウンロードしますか？
必ずではありません。npmの現行仕様では、ローカルProjectに対象packageの実行ファイルがあればそれを利用できます。必要なpackageがローカル依存にない場合は、npx/npm execが取得・実行を提案することがあります。チーム開発ではTypeScriptをdevDependencyへ固定して使う方がバージョンを揃えやすくなります。
npx tscとnpm run typecheckはどちらを使えばよいですか？
単発の確認ならnpx tscでも問題ありません。チームで同じオプションを繰り返すなら、package.json scriptsへtypecheckなどの名前で固定するとCIとローカルの手順を揃えやすくなります。
npx tsc file.tsでtsconfigのstrictが効かないのはなぜですか？
TypeScript公式仕様では、入力ファイルをコマンドラインに指定するとtsconfig.jsonは無視されます。Project設定で確認したい場合はファイルを直接指定せずnpx tscを使うか、-p/–projectで使用するConfigを明示してください。
まとめ：npxとtscの役割を分けて覚える
- npxはnpmパッケージの実行環境を用意し、tscはTypeScript Compilerを実行する
- ProjectへTypeScriptをdevDependencyとして入れるとバージョンを揃えやすい
- 入力ファイルなしのtscは近いtsconfig.jsonを探してProjectをコンパイルする
- ファイルをCLIへ直接指定するとtsconfig.jsonは無視される
- -p/–projectで設定を明示し、–watchで変更監視、–noEmitで型チェック専用にできる
- 繰り返すコマンドはpackage.json scriptsへ固定すると運用しやすい
まずはProjectのルートで`npx tsc –showConfig`を実行し、どの設定が実際に使われているか確認してみてください。そこが分かると、コンパイルエラーの切り分けもかなり進めやすくなります。
