migrate-js-to-modern-typescript

JavaScript から TypeScript への移行におけるベストプラクティス

大規模な一括書き換えを行わずに、JavaScript のコードベースを厳格でモダンな TypeScript に移行するためのガイドです。影響度に基づいて優先順位を付けた 7 カテゴリ・42 のルールを収録しており、ビルドを常に通る状態に保ちながら、ファイル単位で段階的に移行できます。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• .js のコードベースを .ts に変換するとき（プロジェクト全体、または一度に 1 モジュールずつ）
• JSDoc やアノテーションを使って、既存の JavaScript に型を追加するとき
• JavaScript と TypeScript が混在するリポジトリで、tsconfig と allowJs の方針を決めるとき
• 大規模なコードベースで strict モードや個別の strict フラグを有効にするとき
• 手早い変換で残った any、as キャスト、! アサーションを置き換えるとき
• 外部データ（JSON、環境変数、API レスポンス）を検証して、記述した型が実行時にも正しいことを確かめるとき
• CommonJS を ESM に、プロトタイプをクラスに変換するなど、ほかの JavaScript のイディオムを TypeScript に変換するとき
• TypeScript の型チェックと公開に向けて、ビルド、ランナー、CI を更新するとき

移行の流れ

tsconfig & strategy → strictness ratchet → type the surfaces → kill any/casts
   → validate runtime boundaries → convert JS idioms → tooling/build/CI

前半の判断は後続の工程に連鎖します。tsconfig を誤って設定したり、上位から順に変換したりすると、モジュールに二度型を付け直すことになります。また、早い段階で any が大量に発生すると、後続のすべてに悪影響が及びます。このパイプラインの前半から始め、依存グラフの末端から内側へと進めてください。

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	移行のセットアップと tsconfig	CRITICAL	setup-
2	厳格性の段階的な引き上げ	CRITICAL	strict-
3	公開インターフェースの型付け	HIGH	surface-
4	any と安全でないキャストの置き換え	HIGH	unsafe-
5	実行時データの検証	MEDIUM-HIGH	runtime-
6	JavaScript から TypeScript へのイディオム変換	MEDIUM	idiom-
7	ツールとビルドの移行	LOW-MEDIUM	tooling-

クイックリファレンス

1. 移行のセットアップと tsconfig（CRITICAL）

• setup-allowjs-checkjs-bridge — 段階的な移行に向けて allowJs と checkJs を有効にする
• setup-migrate-leaves-first — 依存先の末端から先に変換する
• setup-jsdoc-before-rename — 名前を変更する前に、JSDoc と @ts-check で JavaScript に型を付ける
• setup-prefer-ts-expect-error — エラー抑制には @ts-ignore より @ts-expect-error を優先する
• setup-skiplibcheck-during-migration — skipLibCheck を設定してサードパーティの型によるノイズを抑える
• setup-modern-module-resolution — module と moduleResolution にモダンな組み合わせを設定する
• setup-noemitonerror-isolatedmodules — 安全に出力するため isolatedModules と noEmitOnError を有効にする

2. 厳格性の段階的な引き上げ（CRITICAL）

• strict-enable-flags-incrementally — strict フラグを一度にすべてではなく、1 つずつ有効にする
• strict-prioritize-null-checks — 最も高いバグ検出効果が得られる strictNullChecks を優先する
• strict-no-implicit-any — 型指定のない値をすべて検出するため noImplicitAny を有効にする
• strict-no-unchecked-indexed-access — インデックスの安全性を高めるため noUncheckedIndexedAccess を有効にする
• strict-use-unknown-in-catch — 捕捉したエラーには any ではなく unknown を指定する
• strict-exact-optional-property-types — exactOptionalPropertyTypes で、プロパティがない場合と undefined の場合を区別する

3. 公開 API の型付け（HIGH）

• surface-annotate-exported-signatures — エクスポートされた関数シグネチャに明示的な型注釈を付けます
• surface-replace-jsdoc-with-types — JSDoc の型タグを実際の型注釈に置き換えます
• surface-type-default-params — デフォルト引数と省略可能な引数に正確な型を付けます
• surface-interface-for-object-args — 型の緩いオブジェクト引数を名前付きインターフェースに変換します
• surface-type-callbacks — コールバックと高階関数の引数に型を付けます
• surface-type-class-fields — 代入に頼らず、クラスフィールドの型を宣言します

4. any と安全でない型アサーションの置き換え（HIGH）

• unsafe-prefer-unknown-over-any — 信頼できない境界では any を unknown に置き換えます
• unsafe-eliminate-as-casts — as による型アサーションを型の絞り込みや検証に置き換えます
• unsafe-avoid-double-assertion — 無関係な型を強制する二重アサーションを避けます
• unsafe-type-dynamic-property-access — Record またはインデックスシグネチャで動的なプロパティアクセスに型を付けます
• unsafe-replace-function-type — Function 型を具体的な呼び出しシグネチャに置き換えます
• unsafe-narrow-instead-of-nonnull — 非 null アサーションを使わずに値の型を絞り込みます

5. 実行時のデータ検証（MEDIUM-HIGH）

• runtime-validate-external-data — 境界で外部データを検証します
• runtime-type-environment-variables — 環境変数を一度だけ解析して型を付けます
• runtime-derive-types-from-schemas — 実行時スキーマから静的な型を導出します
• runtime-type-guards-at-boundaries — 型情報のないライブラリの戻り値に対する型ガードを記述します
• runtime-type-json-parse — 検証を通じて JSON.parse の結果に型を付けます

6. JS から TS のイディオムへの変換（MEDIUM）

• idiom-require-to-import — require と module.exports を ESM 構文に変換します
• idiom-prototype-to-class — プロトタイプコンストラクターを class 構文に変換します
• idiom-type-only-imports — 型のみをインポートする場合は import type を使用します
• idiom-replace-arguments-object — arguments オブジェクトをレストパラメーターに置き換えます
• idiom-enum-to-union-or-const — 凍結オブジェクトの列挙型を const オブジェクトまたはユニオン型に変換します
• idiom-default-export-to-named — default export より名前付きエクスポートを優先します
• idiom-optional-chaining-over-guards — 手動の存在確認ガードをオプショナルチェーンに置き換えます

7. ツールとビルドの移行（低〜中）

• tooling-declare-untyped-modules — 型定義のない依存関係にアンビエント宣言を提供します
• tooling-install-types-packages — ライブラリの戻り値を型キャストする前に @types パッケージをインストールします
• tooling-use-tsx-over-ts-node — ts-node のフラグの代わりに tsx を使って TypeScript を直接実行します
• tooling-emit-declaration-files — 移行したライブラリの宣言ファイルを出力します
• tooling-typecheck-in-ci — ビルドとは別に、CI に型チェックのステップを追加します

使用方法

詳細な説明とコード例については、個別のリファレンスファイルをお読みください。

• セクションの定義 — カテゴリー構成と影響レベル
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

関連スキル

• typescript-refactor — すでに TypeScript で書かれたコードのリファクタリングとモダナイズ
• typescript-advanced-patterns — 移行完了後に使う高度な型レベルのパターン

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報