型チェックと実行の最低セット

型チェックと実行の最低セット — TypeScript Tips

TypeScript プロジェクトで毎日使うのは、だいたい 型チェック（tsc --noEmit） と 実行（tsx など） の2つです。VS Code / Cursor のエディタ連携も含め、「書く → 型を見る → 動かす」 のループを package.json の scripts に固定します。

参考: TypeScript — tsc CLI · tsx · VS Code — TypeScript

型チェックと実行は別物

処理	ツール例	やること
型チェック	`tsc --noEmit`	型エラーを報告。JS は出さない
実行	`tsx`, `node`（コンパイル後）	実際にコードを動かす

tsc は型を消した JavaScript を 生成できる コンパイラですが、開発中は noEmit: true と組み合わせて チェック専用 にすることが多いです。実行は tsx が TypeScript をオンデマンドで解釈し、保存→実行のサイクルを短くします。

flowchart LR  Edit["編集 src/*.ts"]  TC["npm run typecheck"]  Run["npm run start"]  Edit --> TC  Edit --> Run  TC --> OK{"エラーなし？"}  OK -->|はい| Run

実行時に型エラーが自動で止まるわけではないので、保存やコミット前に npm run typecheck を回します。

tsc --noEmit で型だけ見る

tsconfig.json（抜粋）

{  "compilerOptions": {    "strict": true,    "noEmit": true,    "module": "NodeNext",    "moduleResolution": "NodeNext"  },  "include": ["src"]}

コマンド

npx tsc --noEmit

--noEmit はコマンドラインでも指定できます。tsconfig に noEmit: true があるなら tsc だけでもファイルは生成されません。

意図的な型エラーの例

// src/bad.tsconst n: number = "文字列";

実行:

npx tsc --noEmit

期待する結果

src/bad.ts:1:7 - error TS2322: Type 'string' is not assignable to type 'number'.

終了コードが 0 以外なら CI や scripts から失敗として扱えます。

tsx でそのまま実行する

tsc で毎回 dist/ に吐いてから node dist/index.js もできますが、学習中は手数が増えます。tsx は TypeScript / ESM をそのまま実行するランナーです。

インストール

npm install -D typescript tsx

実行例

npx tsx src/index.ts

src/index.ts

function main(): void {  const items = ["a", "b", "c"];  for (const item of items) {    console.log(item.toUpperCase());  }}main();

期待する出力

ABC

tsx は開発用です。本番配布前に tsc でビルドする流れは別途ありますが、言語学習の段階では tsx で十分です。

package.json の scripts 設計

scripts は短い名前に固定しておくと、手順がブレません。

{  "name": "jsts-app",  "private": true,  "type": "module",  "scripts": {    "typecheck": "tsc --noEmit",    "start": "tsx src/index.ts",    "dev": "tsx watch src/index.ts"  },  "devDependencies": {    "typescript": "^5.7.0",    "tsx": "^4.19.0"  }}

script	用途
`typecheck`	型だけ確認。CI や保存後の手動実行
`start`	1回実行
`dev`	ファイル変更を監視して再実行（`tsx watch`）

使い方

npm run typechecknpm run startnpm run dev

npm run は package.json の scripts を呼ぶ糖衣です。引数を渡すときは -- を挟みます。

npm run start -- src/other.ts

（start の定義を汎用にするなら "start": "tsx" だけにしてファイル名を引数で渡す方法もあります。）

VS Code / Cursor の型チェック

エディタはバックグラウンドで TypeScript 言語サービスを動かし、赤波線で型エラーを示します。追加プラグインは通常不要です。

確認ポイント

項目	推奨
ワークスペース	`package.json` と `tsconfig.json` があるフォルダを開く
TypeScript バージョン	コマンドパレット →「TypeScript: Select TypeScript Version」→ ワークスペースの `node_modules`
保存時	設定 `editor.codeActionsOnSave` で整理可能（必須ではない）

エディタの表示と tsc は ほぼ一致 しますが、公式のゲートは npm run typecheck と考えてください。CI ではエディタは使えません。

settings.json の例（任意）

{  "typescript.tsdk": "node_modules/typescript/lib",  "typescript.enablePromptUseWorkspaceTsdk": true}

ワークスペースの TypeScript を使うと、バージョン差による奇妙なエラーを減らせます。

日常のワークフロー

src/ に .ts を書く
エディタの赤線を直す
npm run typecheck で全体確認
npm run start または npm run dev で動作確認

  書く → エディタ → typecheck → start/dev         ↑___________________|              エラーがあれば戻る

Docker 環境を使っている場合は、ホストで編集しコンテナで実行します。

docker compose run --rm app npm run typecheckdocker compose run --rm app npm run start

最低限のファイル一覧

project/  package.json      # scripts 定義  tsconfig.json     # strict, noEmit など  src/    index.ts        # エントリ

うまくいかないとき

症状	対処
`tsc: command not found`	`npm install -D typescript` 後は `npx tsc` または npm scripts 経由
エディタにエラーが出ない	フォルダ単位で開いているか。単一ファイルだけ開いていると tsconfig 外扱い
`tsx` で実行時エラーだが typecheck は通る	実行時だけの問題（未定義プロパティアクセスなど）。ロジックと null チェックを見直す
`typecheck` は通るが import 失敗	実行時のモジュール解決。拡張子、`package.json` の `"type": "module"` を確認
`npm run dev` が動かない	`tsx` が `devDependencies` に入っているか、`src/index.ts` のパスが正しいか、`npm install` 済みかを確認
古い `tsc` が使われる	グローバル `tsc` ではなく `npx tsc` / ワークスペース版を選択
Windows で scripts が失敗	パスにスペースがあると困ることがある。プロジェクトパスを短く英数字に

型チェックと実行の最低セット