typescript-typecheck

typescript-typecheck — SKILL.md

バリアント： standard · 使用するタイミング： スキルが呼び出され、最後まで実行されると、設定済みの型チェックゲート（tsconfig + スクリプト + CI ステップ）を返し、制御が呼び出し元に戻ります。

概要

TypeScript のコンパイラー（tsc）は、実際に型をチェックする唯一のツールです。一般的な TS ツールチェーンに含まれるバンドラーやトランスパイラー（Vite（開発時は esbuild、本番時は Rollup）や SWC ベースの React プラグイン）は、型チェックをせずにトランスパイル／型注釈を削除します。つまり、コードに型エラーが大量に含まれていても、vite build（または esbuild／SWC によるビルド）は成功します。このスキルでは、その不足している部分を設定します。厳格な tsconfig を基盤として、ローカルと CI の両方で実行される専用の tsc --noEmit 型チェックゲートを用意し、さらにモノレポ内でパッケージ間の型を解決できるよう、TypeScript の プロジェクト参照を設定します。これは、静的解析ゲートを分けて設けるのと同じ考え方です。リンター（Biome／ESLint）はスタイルやバグのパターンを検出しますが、型システムを持たず、この役割を果たせません。TypeScript 5.x に固定されています。検証済みのフラグ一覧と実例は references/ にあります。

使用するタイミング

• ✅ プロジェクトで初めて TypeScript の型チェックを設定するとき（typecheck スクリプト + CI ステップ）。
• ✅ tsconfig.json を作成または厳格化し、本当に厳格な設定にしたいとき（strict: true にするだけではなく）。
• ✅ Vite／esbuild／バンドラーアプリ用に moduleResolution: "bundler" を設定し、関連するフラグも正しく指定するとき。
• ✅ モノレポで、アプリパッケージがライブラリ／生成パッケージの型を利用できるよう、TypeScript の プロジェクト参照（composite、references、tsc -b）を設定するとき。
• ✅ バンドラーが無視する型エラーでビルドが失敗するよう、CI の型チェックゲート（例：pnpm を使った GitHub Actions）を追加するとき。

次の場合は有効にしないでください：

• タスクが lint／フォーマットのルールに関するものの場合 — それはリンターの役割です（例：biome スキル）。リンターは型チェックを行いません。
• タスクが本番バンドル／ビルド成果物に関するものの場合 — それはバンドラーの役割です（例：vite スキル）。このスキルが担当するのは tsc による チェック のみです。
• タスクが TypeScript の型システムに関する詳細なチュートリアル（高度な条件型／マップ型、ジェネリクスの複雑なテクニック）に関するものの場合 — このスキルの対象は ゲートとその設定 であり、型理論ではありません。
• タスクがモノレポのタスクランナーのパイプライン／キャッシュ設定に関するものの場合 — それはタスクランナーのスキル（例：turborepo）の役割です。このスキルが追加するのは、タスクランナーが実行すべき typecheck タスクのみです。

ワークフロー

ステップ 1：ゲートを分ける理由を理解する（決して省略しない）

この点をしっかり理解し、必要に応じて設定時に明記してください。トランスパイラーは型チェックをしません。

• Vite の公式ドキュメントでは、.ts ファイルのトランスパイルのみを行い、型チェックは行わないとしています。また、「型チェックは IDE とビルドプロセスで行われる」ことを前提とし、tsc --noEmit ステップを明示的に推奨しています。esbuild は「型情報を使わずにトランスパイルのみを実行します」。
• SWC ベースの React プラグイン（@vitejs/plugin-react-swc）も同様です。SWC は型を削除しますが、チェックはしません。Babel／esbuild ではなく SWC を選ぶのは、バンドラー設定で決めるビルド速度の判断です。型チェックが追加されたり省かれたりすることはなく、引き続き tsc ゲートが必要です。

結論：単独の tsc --noEmit（または参照を使う場合は tsc -b --noEmit）ゲートは任意ではなく必須であり、vite build とは別に設定する必要があります。

ステップ 2：本当に厳格な tsconfig を記述する

strict: true は最低ラインであり、上限ではありません。有効になるのは、既知のフラグ群です（全リストと設定例は references/strict-tsconfig.md を参照してください）。 noImplicitAny、strictNullChecks、strictFunctionTypes、strictBindCallApply、strictPropertyInitialization、noImplicitThis、useUnknownInCatchVariables、alwaysStrict。

strict に含まれない、効果の高いフラグも追加します。

• noUncheckedIndexedAccess — インデックスや配列へのアクセス結果に undefined を加えます（strict 以外では、実際のバグを防ぐ効果が最も高いフラグです）。
• noImplicitOverride — override キーワードを必須にし、サブクラスが気づかないうちにずれてしまうのを防ぎます。
• noFallthroughCasesInSwitch、noImplicitReturns — 制御フローの網羅性を確認します。
• noUnusedLocals、noUnusedParameters — デッドコードを検出します（_ で始まるパラメーターは対象外です）。
• exactOptionalPropertyTypes — 「存在しない」場合と「undefined が設定されている」場合を区別します（Gotchas を参照してください。意図を理解したうえで追加するフラグです）。
• verbatimModuleSyntax — 記述した type 修飾子に従って、インポート／エクスポートを正確に削除します（推測による省略は行いません）。

Vite／バンドラーアプリの場合、モジュール関連の設定は次のとおりです。"module": "esnext"（または "preserve"）、"moduleResolution": "bundler"、"noEmit": true、"jsx": "react-jsx"、"isolatedModules": true、"moduleDetection": "force"。厳格な設定を最も簡単に導入するには、"extends": "@tsconfig/strictest" を設定してから、その上にバンドラー向けの設定を重ねます。

ステップ 3：Vite の分割設定レイアウトを採用する（Vite を使う場合）

Vite の TS アプリでは、3 つのファイルが生成されます。2 つの子設定への "references" と "files": [] だけを含むソリューションの tsconfig.json、tsconfig.app.json（src/、DOM ライブラリ、バンドラー解決、noEmit）、tsconfig.node.json（vite.config.ts、Node ライブラリ）です。package.json には "build": "tsc -b && vite build" が設定され、独立した "typecheck": "tsc -b --noEmit" スクリプトを追加します。各子設定で noEmit が設定されているため、ここでの tsc -b は型チェックのみを行います。レイアウトと正確なファイルの内容は references/vite-split-config.md を参照してください。

ステップ 4：モノレポ用にプロジェクト参照を設定する

アプリがライブラリまたは生成されたパッケージ（生成された API クライアントなど）を使用する複数パッケージのリポジトリでは、参照先のパッケージに "composite": true を設定します（これにより "declaration": true が強制され、すべてのソースファイルが include／files に含まれる必要があります）。コンシューマーには "references": [{ "path": "../<pkg>" }] を追加し、tsc -b でビルド／チェックします。参照先プロジェクトからのインポートは、出力された .d.ts を参照して解決されます。また、tsc -b は依存関係を順番にビルドし、.tsbuildinfo を使ってインクリメンタルに処理します。2 パッケージの設定例は references/project-references.md を参照してください。生成された typecheck タスクは、turborepo スキルを使ってモノレポのタスクランナーに組み込みます（キャッシュと依存関係の順序も設定します）。ここでパイプラインを一から組み立てないでください。

ステップ 5：CI ゲートを追加する

プッシュ／PR のたびに typecheck スクリプトを実行する CI ジョブを追加し、型エラーでビルドが失敗するようにします（バンドラーでは型エラーは検出されません）。GitHub Actions の大まかな構成（チェックアウト → キャッシュ付き pnpm と Node → インストール → pnpm run typecheck または turbo run typecheck）は references/ci-gate.md を参照してください。パイプラインとキャッシュの詳細は、タスクランナースキルで扱います。

ルール

厳守するルール（決して違反しないこと）：

• tsc のチェックはビルドとは別です。 vite build／esbuild／SWC が型を検証すると主張したり、そうほのめかしたりしてはいけません。typecheck は独立したスクリプトおよび独立した CI ステップとして維持してください。
• strict: true は必須です。strict だけでは「厳密さが不十分」です。 少なくとも noUncheckedIndexedAccess を追加し、より厳格なベース設定を推奨します。
• スキャフォールドが厳密な設定だと信頼せず、検証してください。 新しく作成した tsconfig.app.json に strict: true が含まれていない場合があります。ファイルを開いて確認するか、extends: "@tsconfig/strictest" を使用してください。決して思い込まないでください。
• プロジェクト参照を使う場合は、tsc 単体ではなく tsc -b でチェックしてください。 ソリューションファイルに対する tsc -p 単体では references グラフが無視されます。tsc -b（ビルドモード）はグラフをたどり、インクリメンタルに処理します。
• composite: true にすると declaration: true が強制され、すべてのファイルを include／files に含める必要があります。 outDir／tsBuildInfoFile は意図的に設定してください。

推奨事項（変更可能）：

• 厳密さの最低ラインとして extends: "@tsconfig/strictest" を優先し、その後、プロジェクトに合わせて module／jsx ブロックを上書きしてください。
• バンドラーを使うアプリでは module: "esnext"（または "preserve"）と moduleResolution: "bundler" を、Node ライブラリでは nodenext を優先してください。
• 迅速なエディター内／開発中のフィードバックには vite-plugin-checker を使ってください。ただし、CI の tsc ゲートに加えて使用し、決して代わりにはしないでください。
• 速度とのトレードオフを理解したうえで、デフォルトでは skipLibCheck: true を維持してください（注意点を参照）。

注意点

• 「vite build が成功したので、型も問題ありません。」 これは誤りです。このスキルが防ぐ最も重大な間違いです。バンドラーは型を取り除いており、型をチェックしたのは tsc --noEmit だけです。必ず typecheck スクリプトを個別に実行してください。
• スキャフォールドは自動的に厳密な設定になるわけではありません。 現在の create-vite の react-ts 用 tsconfig.app.json にはバンドラーおよび lint のフラグが含まれていますが、実際に strict: true が設定されているか確認する必要があります（テンプレートのバージョンによって変化してきました）。追加するか、extends: "@tsconfig/strictest" を設定してください。
• moduleResolution: "bundler" には必須の組み合わせがあります。 module は esnext または preserve でなければならず、commonjs は使えません。allowImportingTsExtensions: true が有効なのは、noEmit（または emitDeclarationOnly）が設定されている場合に限られます。これは型チェックのみを行う構成にぴったりですが、これを有効にしたまま JavaScript を出力するとエラーになります。
• exactOptionalPropertyTypes には注意が必要です。 これを有効にすると、{ a?: string } は { a: undefined } を受け付けなくなります。許可するには a?: string | undefined と書く必要があります。この設定が strict に含まれていないのはこのためです。意図的に追加し、省略可能プロパティを使う箇所の修正が必要になることを想定してください。
• 参照を使う構成で tsc -b を忘れないでください。 references しかないソリューションの tsconfig.json に対して tsc --noEmit を実行しても、有用なチェックは行われません。グラフをたどるのはビルドモード（tsc -b）です。typecheck スクリプトでは -b を使ってください。
• skipLibCheck: true は実際のエラーを隠します。 生成されたクライアントの出力宣言や、競合する node_modules のライブラリ型も含め、すべての .d.ts の型チェックを省略します。これは速度とノイズを意図的にトレードオフする設定です。生成された .d.ts 自体に不備があっても、この設定によって見逃されます。
• verbatimModuleSyntax を使う場合は、import type を明示する必要があります。 これを有効にすると、型を値としてインポートした場合に削除されず、実行時にクラッシュすることがあります。型だけのインポートには import type を指定してください。この設定は、非推奨の importsNotUsedAsValues／preserveValueImports に取って代わります。

アンチパターン

• 「リンターがあるので、tsc は必要ありません。」 リンター（Biome／ESLint）には型システムがないため、型エラーを検出できません。型チェックのゲートは必須であり、Lint とは別のものです。
• 「SWC プラグインに切り替えたので、tsc の手順は不要になりました。」 いいえ。SWC は高速なトランスパイラーですが、型チェックは行いません。ビルドプラグインの選択と型チェックのゲートは別々のものです。
• 「skipLibCheck を有効にすれば、エラーはなくなります。」 抑制されるのは宣言ファイルのエラーであり、コードのエラーではありません。また、壊れた生成済みの .d.ts が見逃されることもあります。実際の型エラーを黙らせるために使わないでください。
• 「strict: true を設定すれば、設定を strict と呼べます。」 それは最低限の strict 設定にすぎません。追加のフラグ（最低でも noUncheckedIndexedAccess）を設定するか、最も厳格なベース設定を使ってください。
• 「CI で vite build に型の問題を検出させればよいでしょう。」 検出されることはありません。CI のゲートでは、独立した手順として（直接、またはタスクランナー経由で）tsc／tsc -b --noEmit を実行する必要があります。

出力

プロジェクトで機能する TypeScript 型チェックのゲートです。実際に strict な tsconfig セット（該当する場合はソリューション設定とリーフ設定）、ビルドとは別の独立した typecheck npm スクリプト（tsc --noEmit または tsc -b --noEmit）、使用するパッケージまたは生成するパッケージに設定されたプロジェクト参照、そしてチェックを実行して型エラーがあれば失敗する CI 手順が含まれます。次のワークフローフェーズで利用するのは、バンドラーでは提供されない型エラーのゲートと、それを適用する CI を得た開発者またはディスパッチされたエージェントです。

関連項目

• biome（または任意のリンタースキル）— Lint／フォーマットを補完するものです。型チェックは行わないため、このスキルが必要です。
• vite — ビルド／バンドルを担当します。このスキルが担当するのは、ビルドで省略される tsc のチェックのみです。
• turborepo — モノレポのタスクパイプライン／キャッシュを担当します。このスキルでは、実行する typecheck タスクを提供します。
• Python における概念上の類似例（ツールチェーンは異なります）：ty のような独立した Python 型チェッカーは、ここでの tsc --noEmit と同じ「独立した型チェックのゲート」の役割を Python で果たします。

段階的な情報開示

• references/strict-tsconfig.md — strict ファミリー、推奨する追加フラグとその正確な動作、バンドラー用のモジュール設定ブロック、共有可能なベース設定、そして strict な tsconfig.app.json の実例です。tsconfig を作成または強化する際に読み込んでください。
• references/vite-split-config.md — Vite の 3 ファイル構成の TypeScript レイアウト、tsc -b && vite build と typecheck の各スクリプト、vite-plugin-checker について説明します。Vite アプリの型チェックを設定する際に読み込んでください。
• references/project-references.md — composite／references／tsc -b／incremental のセマンティクスを、2 パッケージ（app → generated-client）の実例と skipLibCheck とともに説明します。モノレポを設定する際に読み込んでください。
• references/ci-gate.md — tsc CLI フラグのリファレンス、GitHub Actions のゲート構成、検証済みの tsgo／typescript-go のステータスに関する注記です。CI を追加する場合や、ネイティブコンパイラーについて質問された場合に読み込んでください。
• references/sources.md — 調査の出典情報です。

本文の上限

• description は 1,024 文字以下です。
• 本文は約 500 行／5,000 トークン以下です。大量の内容は references/ に置き、必要に応じて読み込みます。