TypeScript導入で詰む7ポイント — JS→TS移行の実務

JavaScript から TypeScript への移行は、表面的には tsconfig.json と型定義の追加に見える。だが実務で詰まるのは別の構造的問題である。strict モードの段階有効化、any と unknown の使い分け、ビルド速度の悪化、混在期のテスト戦略、レビュー文化の変化。本記事は、移行を完遂した中堅エンジニアの観点から、JS→TS 移行で詰む7つのポイントを順序立てて整理する。

なぜ TypeScript 移行は「7ポイント」で詰まるのか

移行の最初の壁は、tsconfig.json で全部を strict にしようとして膨大な型エラーに埋もれることである。TypeScript 公式 TSConfig リファレンスは、strict は noImplicitAny・strictNullChecks など複数のオプションの集合だと明示している。各オプションを段階有効化することで、移行コストを管理可能な範囲に収めるのが基本戦略になる。

2026 年の TypeScript 6.0 では strict がデフォルトで true になったが、既存 JS プロジェクトを 6.0 にいきなり上げると、全ファイルで型エラーが噴出する。中堅期のエンジニアが移行を主導するなら、strict 設定の段階制御は最初に習得すべき技能である。

strict モードを「いつ」有効化するか

strict を最初から true にすると初期コストが膨大、最後まで false で運用すると恩恵を享受できない。移行段階ごとに、strict 配下の各オプションを段階有効化していく順を持つのが現実的である。

移行初期は allowJs: true と checkJs: false で .js と .ts を混在させ、新規ファイルだけ .ts で書く。次に noImplicitAny を有効化し、暗黙の any を明示的な any または unknown に置き換える。続いて strictNullChecks を有効化し、null/undefined を独立した型として扱う。最後に noUncheckedIndexedAccess・useUnknownInCatchVariables を有効化して締める。

段階的 tsconfig 管理を支援するツールとして、ts-migrating プラグインのように、ファイルごとに目標 tsconfig を持ちつつ、未対応行だけ古い設定にフォールバックさせる仕組みも公開されている。チーム規模が大きくなるほど、こうしたツールの導入が現実的になる。

strict モードの効用と運用設計の解説は、海外の SaaS 系オブザーバビリティ企業の OneUptime が公開する TypeScript Strict Mode Guideでも整理されており、特に noImplicitAny と strictNullChecks の段階導入を「最初の2マイルストーン」として位置付けている。チーム合意を取る材料として有用である。

any と unknown の使い分け

移行期に any を散らすと、負債が固定化する。後から unknown に置き換えようとしても、any を経由する箇所が連鎖して広がっているため、削減が難しくなる。

判断軸はシンプルである。型が確実に分かるなら具体型、確実に分からないが値の正体を後で検証するなら unknown、検証する気がないなら any。中堅エンジニアが現場で詰まるのは「気がない」を「分からない」と混同する場面である。チームで any の利用ルールを明文化し、ESLint の no-explicit-any で機械的に検出する運用が、移行期の負債固定化を防ぐ。

renue 社内のフロントエンド開発でも、API 戻り値の型運用について any 型多用が課題として明確に指摘されたことがある。型ガード関数を用意して unknown を経由する書き方は、社内で共有されたベストプラクティスになっている。

既存 JS ライブラリの型定義 — @types とアンビエント宣言

DefinitelyTyped にない、または古いライブラリの型定義をどう補完するかは、移行期の隠れたコストになる。@types パッケージを探す、なければ自前で declare module を書く、ライブラリの最新バージョンに上げて公式型を取り込む、の3択を判断する必要がある。

declare module の最小ユニットは、エクスポート名と最低限の型シグネチャだけを書くことである。完璧な型を書こうとすると挫折する。「使うところだけ書く」「他は any でも構わない」と割り切る判断が、移行期には合理的になる。

AWS が公開する TypeScript のベストプラクティスを順守 — AWS 規範ガイダンスも、エンタープライズ環境での型定義保守の指針として参照価値がある。CDK のような大規模ライブラリでの型定義運用は、自社の TypeScript 移行のスケール感を想定する材料になる。

ビルド速度の落とし穴 — incremental と project references

TS 化でビルド速度が悪化し、開発体験が落ちるチームは多い。incremental: true、composite: true、project references の組合せで速度を取り戻すのが定石だが、設定の組合せを誤ると逆効果になる。

incremental は型情報をキャッシュして次回ビルドを高速化するオプション。tsBuildInfoFile の出力先を CI と開発者ローカルで揃えると、CI のキャッシュ効果も上がる。composite と project references は、モノレポでパッケージ間の依存を切るときに有効になる。

2026 年は TypeScript 7 で Go 製の高速コンパイラが登場することが予告されており、tsc の速度は今後さらに改善する見込みである。中堅期に project references の概念を理解しておくと、コンパイラ進化のメリットを取り込みやすくなる。

型レベルプログラミングの「やりすぎ」境界

Conditional Types・Mapped Types・Template Literal Types は強力だが、可読性を下げる転換点がある。型定義を読み解くのに 30 分以上かかるなら、それは「型レベルプログラミングのやりすぎ」を示すサインである。

中堅期のエンジニアが踏み越えがちな境界は、業務ロジックで再利用しない型を抽象化しすぎる点にある。Prisma が自動生成する型のように「ライブラリレベルでは厳密、利用側ではシンプル」が理想形である。renue 社内で Prisma を利用する TypeScript プロジェクトでも、生成された型は厳密だが、アプリケーションコードからは具体的な Model 型として参照しており、型操作のオーバーヘッドをユーザ側に持ち込んでいない。

判断軸は「型エラーを治す時間が業務時間の半分を超えたら、設計を疑う」である。型定義のためにアプリケーションコードを書く時間が削られる本末転倒を避けるのは、中堅エンジニアの設計責任になる。

JS と混在期のテスト戦略

.js と .ts が混在する移行期は、ユニットテストの型互換性が崩れやすい。Jest や Vitest での型解決設定、tsconfig の paths と Jest の moduleNameMapper の整合性、E2E テストの責務分担。これらを移行のフェーズに応じて整える必要がある。

移行初期は Jest を ts-jest 経由で動かし、.js テストも .ts テストも両方走らせる。中期になったら .js テストを .ts に移行する優先度を、コードカバレッジの数値で判断する。終盤では型エラーをテストの失敗として CI で検出する運用に切り替える。

E2E テストは、移行のフェーズに関係なくフレームワークと別レイヤーで動くため、優先度を下げて構わない。ユニットテストの型整備が終わった後で、E2E の言語移行に手を付ける順序が現実的である。

チーム全員のスキル底上げ — レビュー文化の変化

TS 化はコードレビューの観点を変える。型シグネチャの妥当性、Generics の必要性、any の混入チェック。これらを全員でできるようにする「レビュー基準の言語化」が、移行を持続させる組織的な装置になる。

ジュニアが書いた型ミスをレビューで矯正する時、責めるのではなく「なぜこの型が必要か」を説明できるレビュアーをチームに増やすことが、TS 移行の質を決める。中堅エンジニアの役割は、自分が書くより「他人が書ける環境を作る」方に重みが移っていく。

AI コード生成（Claude Code・Copilot 等）が型推論を補助する場面は増えている。だが「この型でなぜ正しいか」を言語化できるのは人だけである。レビュー文化を AI 時代に再設計する観点でも、TS 移行は組織のレビュー基準を整える機会になる。

中堅エンジニアが TS 移行を主導するときの判断軸

7ポイントを越えると、移行はチームの設計スキル全体を底上げする機会になる。Strict 設定の段階制御、any/unknown の規律、@types とアンビエント宣言の判断、ビルド速度の管理、型レベルプログラミングの境界、混在期のテスト戦略、レビュー文化の変化。それぞれが独立した技能であり、独立して練習できる。

AI エージェントは tsc のエラー解釈、型推論の補助、リファクタリングの提案では既に強力なパートナーになっている。Claude Code や Copilot が型変換のドラフトを生成し、人がレビューする分担が標準になりつつある。だが「どこまで strict にするか」「どこで any を許容するか」「型レベルプログラミングの境界をどこに引くか」は、人の設計判断が中心であり続ける。

中堅期に TS 移行を主導することで身につく判断力は、テックリード・スタッフエンジニア・スタートアップ CTO のキャリアパスでも資産になる。型システムへの理解は、技術選定・チーム作り・組織設計まで含めた中堅エンジニアの基礎体力を底上げする。