typescript-migration

TypeScript の移行

TypeScript 5.x → 6 → 7（ネイティブ Go 版）への正式な移行ガイドです。Microsoft の公式発表を参照しています。

ステータス

• スキルのステータス：本番環境で利用可能
• 最終更新日：2026-07-09
• TS 6.0 リリース：2026-03-17（最終版）— JavaScript ベースの最後のリリース
• TS 7.0 リリース：2026-07-08 — ネイティブ Go 版（「Corsa」）、安定版
• 正式な情報源：
  • TS 7.0 リリース：https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
  • TS 6.0 ベータ版：https://devblogs.microsoft.com/typescript/announcing-typescript-6-0-beta/
  • TS 6 → 7 の差分トラッカー：https://github.com/microsoft/typescript-go/blob/main/CHANGES.md
  • ts5to6 ツール：https://github.com/andrewbranch/ts5to6

黄金律

TypeScript 6 を絶対に飛ばさないでください。サポートされている移行経路は 5.x → 6 → 7 のみです。

TS 6 を飛ばすと、TS 7 では TS 6 で非推奨になったすべての機能が削除されているため、大量の重大なエラーが発生します。"ignoreDeprecations": "6.0" は TS 6 内で一時的に移行を保留する場合に限って使用してください。TS 7 では機能しません。

クイックトリアージ（1 分）

1. 現在のバージョンを検出する — scripts/detect-ts-version.sh を実行します（package.json を読み込みます）。
2. 移行経路を判定する：
   • 5.x → references/migration-playbooks.md §「5.x → 6」から始めます。
   • 6.x → TS 7 に直接移行できます（references/ts7-go-rewrite.md を参照）。
   • TS 7 を目指す 5.x → 5 → 6 → 7 の順に進める必要があります（近道はありません）。
   • バージョンを変更せずに厳格フラグを段階的に適用する場合 → オプションの ts-migrating ツールについて references/ts-migrating-tool-guide.md を参照してください。
3. 変更を始める前に監査する — scripts/audit-ts7-breakers.sh を実行して、TS 7 で問題が発生するツール（typescript-eslint、ts-morph、ts-node、Vue/Svelte/Astro/MDX/Angular テンプレート、ts-patch、ttypescript、typia、baseUrl、node10、ES5 ターゲット）を検出します。

プロジェクト種別の判断マトリックス

プロジェクト種別	推奨事項	理由
新規プロジェクトで、API に依存するツールを使用しない	TS 7 を直接採用する	最大限の高速化が得られ、阻害要因がありません
既存の TS プロジェクトで、特別なツールを使用しない	5 → 6 → 7 の順に移行する	TS 6 では、非推奨の項目がまずすべて警告として示されます
typescript-eslint / ts-morph / API 利用ツールを使用する	@typescript/typescript6 を併用しながら 5 → 6 → 7 へ移行する	TS 7 では 7.1 までプログラム用 API がありません
Vue / Svelte / Astro / MDX（Volar ベース）	TS 6 を使い続ける	Volar にはプログラム用 API が必要ですが、まだサポートされていません
テンプレートの型チェックを使用する Angular	CLI には TS 7、エディターには TS 6 を使用する	Microsoft 公式の分割回避策です
ts-patch / ttypescript / typia / カスタム AST トランスフォーマー	Oxc/SWC に移行するまで TS 6 を使い続ける	TS 7 ではトランスフォーマー API が廃止されています

TS 6 — 主な破壊的変更（概要）

変更	以前のデフォルト	TS 6 のデフォルト	対処方法
strict	false	true	明示的に設定するか、エラーを修正します
module	CommonJS	esnext	必要に応じて commonjs を設定します
target	ES3	es2025（変動）	明示的に設定します
moduleResolution	node10	bundler	Node ターゲットには nodenext を設定します
rootDir	推論	.（tsconfig のディレクトリ）	"rootDir": "./src" を設定します
types	すべての @types	[]	"types": ["node"] を設定します
esModuleInterop	false	true	:false を削除し、import * as を import に修正します
noUncheckedSideEffectImports	false	true	タイポを修正するか、バンドラーの CSS では false を設定します
libReplacement	true	false	—
allowSyntheticDefaultImports	変動	true	—

6 で非推奨になり、7 では 重大なエラー になります：target: es5；downlevelIteration；moduleResolution: node | node10 | classic；module: amd | umd | systemjs | none；baseUrl；esModuleInterop: false；allowSyntheticDefaultImports: false；alwaysStrict: false；outFile；キーワードとしての module Foo {}；インポートでの assert { }；/// <reference no-default-lib="true"/>；tsconfig が存在する状態での tsc <file>（--ignoreConfig を使用してください）。

PR の出典、例、公式 ts5to6 codemod の使用方法を含む各変更の詳細については、references/ts6-breaking-changes.md を読み込んでください。

TS 7 — 変更点（クイックビュー）

• Go によるネイティブ移植版です。標準の typescript npm パッケージが TS 7 です（npm install -D typescript）。
• TS 6 のすべての非推奨項目が致命的なエラーになります（上の表を参照）。
• 7.0 にはプログラムから利用できる Compiler API がありません。新しい API は TS 7.1 で提供される予定です。ts-morph、ts-node、ts-jest、ts-loader、ts-patch、ttypescript、typia、typescript-eslint に影響します（以下のサイドバイサイドパターンを使用してください）。
• preserveConstEnums は削除されました。常に const enum を出力します。
• stableTypeOrdering はデフォルトで true になり、無効にできません。
• 新しいフラグ：--checkers N（デフォルトは 4）、--builders N、--singleThreaded。
• 新しい破壊的変更：テンプレートリテラル型で Unicode コードポイントが保持されます（UTF-16 コード単位ではありません）。
• 新機能：JavaScript ファイルの処理が見直されました（Closure スタイルの @enum、@class、?、後置の ! は特別扱いされなくなりました）。
• パフォーマンス（公式発表、実際の OSS コードベース）：ビルドが 7.7～11.9 倍高速化（--checkers 8 では最大 16.7 倍）。メモリ使用量は 6～26％削減。

インストール方法の詳細、互換性マトリックス、パフォーマンステーブル、既知の問題については、references/ts7-go-rewrite.md を参照してください。

公式のサイドバイサイドパターン（TS 7 + TS 6 API）

ツールが TS Compiler API に依存するプロジェクト向けに Microsoft が推奨する方法です。package.json にエイリアスを宣言します。

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

• npx tsc は（@typescript/native エイリアスを介して）TS 7 を実行します。
• typescript をインポートするツール（typescript-eslint、ts-morph）は、@typescript/typescript6 を介して TS 6 の API を透過的に取得します。
• TS 6 の呼び出しを直接実行する必要がある場合は、tsc6 実行ファイルも利用できます。
• TS 7.1 で新しい API が提供されたら、この回避策を削除してください。

標準の 4 ステップワークフロー

1. 検出 — scripts/detect-ts-version.sh でインストール済みのバージョンを確認します。
2. 監査 — scripts/audit-ts7-breakers.sh で、アップグレード前に問題となる項目を検出します。scripts/ts6-deprecation-scan.sh で、tsc の出力から TS5xxx コードを抽出します。
3. 移行 — 適切な手順については references/migration-playbooks.md に従ってください。ユーザーが明示的に承認した場合は、ts5to6 --fixBaseUrl と ts5to6 --fixRootDir を実行します（これらは Microsoft が公式に推奨するコード変換ツールです）。それ以外の変更はすべて手動で行います。
4. 検証 — scripts/compare-tsc7-tsc6.sh で、TS 7 の tsc と TS 6 の tsc6 の診断コードを比較します。コンパイラー間で文言が異なるため、メッセージのテキストではなく TSxxxx コードで照合してください。TS 7 を初めて実行する前に、古い .tsbuildinfo ファイルを削除してください（JavaScript コンパイラーと Go コンパイラーの間で互換性がありません）。

重要なルール

必ず行うこと

• ✅ TS 6 を経由して移行してください。TS 6 を飛ばしてはいけません。
• ✅ メッセージの文言ではなく、診断コード（TSxxxx）で照合してください。
• ✅ TS 7 を初めて実行する前に、古い .tsbuildinfo を削除してください。
• ✅ Microsoft の公式ブログ記事を信頼できる情報源として引用し、サードパーティーのチュートリアルは二次情報として扱ってください。
• ✅ アップグレード前に必ず audit-ts7-breakers.sh を実行してください。

絶対に行わないこと

• ❌ 安定版での使用に @typescript/native-preview をインストールしないでください。これは従来の nightly パッケージであり、安定版は標準の typescript パッケージです。
• ❌ references/unverified-claims.md に記載された、検証されていないサードパーティーの主張を断定しないでください（例：「moduleResolution のデフォルトは node16」、「--ts6-migration フラグが存在する」、「6 では ES5 ターゲットが削除された」、「--keyofStringsOnly が削除された」）。
• ❌ TS バージョンの移行に ts-migrating（ツール）を推奨しないでください。これは同一バージョン内で compilerOptions を厳格化するためのツールです。
• ❌ TS 7 を有効にするために VS Code の設定キーが必要だと想定しないでください。公式拡張機能をインストールすれば、自動的に有効になります。
• ❌ カスタムスクリプトでユーザーのソースコードを自動編集しないでください。検出・監査スクリプトと、公式に認められたコード変換ツール（ts5to6）のみを使用してください。

ts-migrating ツール — 条件付きで案内

既存の大規模コードベースで、より厳格な compilerOption（例：noUncheckedIndexedAccess、strict、erasableSyntaxOnly）を有効にしたい場合に限り、このツールを案内してください。バージョン移行には使用しません。

適用条件（すべて満たす必要があります）：

• 既存の TypeScript プロジェクトであり、新規作成ではない。
• compilerOption を段階的に有効にすることが目的である。
• tsgo / TS-7 への移行ではない。

注意事項：

• annotate サブコマンドはソースを書き換えます。git ツリーがクリーンな状態で実行し、差分を確認してください。
• IDE プラグインは tsc にまったく影響しません。効果を得るには、ts-migrating check を CI に組み込んでください。
• // @ts-migrating マーカーは、整理して削除する必要がある技術的負債です。
• これは Airbnb の ts-migrate ではありません（別のツールです。JS → TS 変換用）。

インストール、コマンド、適用条件のロジックについては、references/ts-migrating-tool-guide.md をご覧ください。

よくあるエラーコード

コード	意味	対応
TS5011	rootDir の不一致	"rootDir": "./src" を設定
TS5101	オプションが非推奨になり、TS {ver} で使用できなくなる	"ignoreDeprecations": "6.0"（TS 6 のみ）を追加するか、修正
TS5102	オプションが削除された	tsconfig から削除
TS5107	オプション=value が非推奨	TS5101 と同様
TS5108	オプション=value が削除された	削除
TS5111	移行情報（baseUrl、node10）	references/ts6-breaking-changes.md を参照
TS5112	tsc のファイル引数と tsconfig が同時に指定されている	--ignoreConfig を使用

参照ファイルを読み込むタイミング

上記のクイックリファレンスだけでは足りない場合は、以下の参照ファイルを読み込んでください。

このファイルを読み込む	次の場合
references/ts6-breaking-changes.md	TS 6 に移行する場合。各デフォルト変更、非推奨化、構文変更について、PR の引用付きで詳しく確認する必要がある
references/ts7-go-rewrite.md	TS 7 を採用する場合。インストールの詳細、互換性マトリックス、パフォーマンス表、既知の未対応項目を確認する必要がある
references/ecosystem-compatibility.md	特定のツール（typescript-eslint、ts-morph、ts-node、vite、webpack、vitest など）が TS 7 で動作するか確認する場合
references/migration-playbooks.md	5→6、6→7、または 5→7（6 経由）の順序付きチェックリストが必要な場合
references/ts-migrating-tool-guide.md	既存の大規模コードベースで、より厳格な compilerOption を段階的に有効にしたい場合
references/unverified-claims.md	公式情報源と矛盾する主張に遭遇し、断定する前に検証する場合

依存関係

• 移行に必須：typescript（移行先のバージョン）、プロジェクトルートの tsconfig.json。
• 任意のヘルパー：
  • @andrewbranch/ts5to6 — baseUrl / rootDir 用の公式 codemod。
  • @typescript/typescript6 — TS 7 向けの並行 API 互換性。
  • ts-migrating — 厳格化フラグを段階的に導入（ガイドを参照）。

パッケージバージョン（2026-07-09 確認済み）

{
  "devDependencies": {
    "typescript": "^7.0.2",
    "@typescript/typescript6": "^6.0.2"
  },
  "optionalHelpers": {
    "@andrewbranch/ts5to6": "latest",
    "ts-migrating": "latest"
  }
}

このスキル内のすべての事実には、Microsoft の公式 TypeScript ブログ（devblogs.microsoft.com/typescript）の出典が記載されています。公式情報源と矛盾するサードパーティのチュートリアルの主張は references/unverified-claims.md にまとめ、疑わしい情報として扱っています。