TypeScript 6.0 → 7.0 移行ガイド — Go製コンパイラ時代に備える破壊的変更まとめ

「動いてるから大丈夫」が一番危ない

TypeScript 6.0 がリリースされ、多くのプロジェクトで npm install typescript@latest を実行した瞬間、ターミナルが警告で埋まった——という体験をした方は少なくないはずです。

しかし本当の問題は、警告が出ること自体ではありません。"ignoreDeprecations": "6.0" を tsconfig.json に1行追加すれば警告は消えます。問題は、その1行で「対応完了」にしてしまうことです。TypeScript 7.0 では非推奨オプションが完全に削除されるため、6.0 での先送りは 7.0 でのビルド不能に直結します。

この記事では、TypeScript 6.0 の破壊的変更を「7.0 への橋渡し」として整理し、今やるべきことと後回しにしていいことを明確に切り分けます。

TypeScript 6.0 は「最後の JS 製コンパイラ」

まず背景を押さえましょう。TypeScript 6.0 は、JavaScript で書かれた最後の TypeScript コンパイラです。次のメジャーバージョン 7.0（コードネーム: Project Corsa）は Go 言語で書き直された tsgo がメインコンパイラになります。

公式ベンチマークでは、tsgo は従来の tsc に対して最大10倍の型チェック速度と3倍のメモリ削減を実現しています。これは大規模プロジェクトにとって革命的な数字です。

つまり 6.0 の役割は明確で、**7.0 に移行できないプロジェクトを作らないための「最終警告リリース」**です。

破壊的変更の全体像

6.0 の変更は大きく3カテゴリに分けられます。

1. デフォルト値の変更（既存コードが壊れる可能性あり）

オプション	5.x までのデフォルト	6.0 のデフォルト
`strict`	`false`	`true`
`module`	`commonjs`	`esnext`
`target`	`es3`	`es2025`（年度自動更新）
`types`	全 `@types/*` を自動読み込み	`[]`（空配列）
`esModuleInterop`	`false`	`true`（false 設定不可）

ここで最もインパクトが大きいのは strict のデフォルト true 化です。

今まで明示的に "strict": true を書いていたプロジェクトには影響ありませんが、デフォルトに頼っていたプロジェクトでは一気に型エラーが噴出します。私自身、あるレガシープロジェクトの移行で strict 未設定のまま 6.0 に上げた結果、1,200件以上の型エラーが出た経験があります。tsconfig.json に "strict": false を明示すれば元の挙動に戻せますが、7.0 時代に strict なしで運用し続けるのは型安全性の観点から推奨しません。

もう一つの地雷は types のデフォルト空配列化です。5.x までは node_modules/@types/ 以下を自動で読み込んでいましたが、6.0 では明示的に指定しない限り読み込まれません。Jest や Vitest のグローバル型（describe, it, expect）が突然見えなくなったら、これが原因です。

{
  "compilerOptions": {
    "types": ["vitest/globals", "node"]
  }
}

2. 廃止されたオプション（7.0 で完全削除）

以下のオプションは 6.0 で非推奨警告が出ます。"ignoreDeprecations": "6.0" で警告を消せますが、7.0 では設定ファイルごと読み込みエラーになります。

モジュール関連:

moduleResolution: "classic" → "nodenext" または "bundler" に移行
moduleResolution: "node"（node10）→ "nodenext" に移行
module: "amd" / "umd" / "systemjs" → "esnext" または "nodenext" に移行

出力関連:

target: "es5" → "es2015" 以上に変更（ES5 が必要なら esbuild で後処理）
outFile → バンドラー（esbuild, Rolldown）に移行
downlevelIteration → target が ES2015 以上なら不要

その他:

baseUrl → paths のエントリにプレフィックスを追加して対応
module キーワード（namespace のエイリアス）→ namespace に統一

3. 挙動変更（コードの修正が必要な場合あり）

import ... assert → import ... with: Import Assertions から Import Attributes への構文変更。assert キーワードはエラーになります
CommonJS ファイルへの "use strict" 自動挿入: ESM は元々 strict なので影響なし。CJS で非 strict な挙動に依存していたコードは注意
rootDir のデフォルト変更: 推論ではなく tsconfig.json のあるディレクトリがデフォルトに

実践: 移行チェックリスト

以下の手順で段階的に移行するのが最も安全です。

Step 1: まず 6.0 にアップデートして現状把握

# TypeScript 6.0 にアップデート
npm install typescript@6

# ignoreDeprecations なしでビルドし、警告を全て確認
npx tsc --noEmit

この時点で出る警告が「7.0 までに対応すべきリスト」です。スクリーンショットを撮るか、出力をファイルにリダイレクトして保存してください。先に ignoreDeprecations を入れてしまうと、何が問題なのか見えなくなります。

Step 2: moduleResolution を移行（最優先）

最も広範囲に影響し、かつ最も対応が面倒なのが moduleResolution です。

// Before
{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

// After（バンドラー使用プロジェクト）
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

// After（Node.js 直接実行プロジェクト）
{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext"
  }
}

nodenext を選んだ場合、相対インポートに拡張子が必須になります。これが移行の最大のハードルです。

// NG: nodenext では解決できない
import { helper } from "./utils";

// OK: 拡張子を明示
import { helper } from "./utils.js";

「.ts ファイルなのに .js で import するのは気持ち悪い」——わかります。しかしこれは Node.js の ESM 仕様に準拠した正しい挙動です。バンドラー経由のプロジェクトなら "bundler" を選べばこの制約はありません。

判断基準:

Vite / webpack / esbuild 等のバンドラーを使っている → "bundler"
Node.js で直接実行する（CLIツール、サーバー等）→ "nodenext"

Step 3: target と module を更新

{
  "compilerOptions": {
    "target": "es2022",
    "module": "esnext"
  }
}

target は実際のランタイム環境に合わせて選びます。2026年時点でブラウザ向けなら es2022 以上、Node.js 20+ なら es2022、最新環境なら es2025 が妥当です。

Step 4: types を明示的に指定

{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  }
}

プロジェクトで実際に使っている @types/* パッケージをリストアップしてください。node_modules/@types/ ディレクトリを見れば一覧がわかります。

ls node_modules/@types/

Step 5: tsgo で事前チェック（任意だが強く推奨）

TypeScript 7.0 のプレビュー版を使って、移行後のコードが 7.0 でも通るか確認できます。

npm install -D @typescript/native-preview

# tsgo で型チェック
npx tsgo --noEmit

tsgo と tsc で異なるエラーが出る場合があります。これは型の順序付けの違いによるもので、--stableTypeOrdering フラグを 6.0 側で有効にすると差分を減らせます。

よくある誤解と落とし穴

「ignoreDeprecations を設定すれば安全」

誤解です。 "ignoreDeprecations": "6.0" は 6.0 の警告を消すだけで、根本的な解決にはなりません。7.0 では非推奨オプション自体が削除されるため、tsconfig.json の解析段階でエラーになります。CI/CD パイプラインが突然壊れる未来が確定するだけです。

「tsgo は tsc の完全な置き換え」

まだ完全ではありません。 2026年3月時点で、tsgo は tsc の約20,000コンパイラテストケースのうち、エラーを出すべき約6,000ケースでほぼ一致していますが、74件の差異が残っています。Language Server（エディタ連携）も開発中です。プロダクションビルドに使う前に、自分のプロジェクトで npx tsgo --noEmit を実行して確認することを推奨します。

「ES5 対応が不要なら影響ない」

ほぼ正しいですが、落とし穴があります。 target: "es5" を使っていなくても、downlevelIteration や outFile を設定していると非推奨警告が出ます。特に outFile はバンドラーに移行する必要があり、これは単純な設定変更では済みません。

「strict: true を明示していたから問題ない」

8割正しいですが、types の罠があります。 strict を明示していても、types をデフォルトに頼っていた場合、テストフレームワークのグローバル型やビルドツールの型定義が見えなくなります。CI でだけ落ちてローカルでは通る、というパターンに注意してください。

移行の優先度マトリクス

すべてを一度に対応する必要はありません。影響度と緊急度で整理します。

優先度	対応項目	理由
今すぐ	`moduleResolution` の移行	影響範囲が最も広く、7.0 で完全削除
今すぐ	`types` の明示的指定	CI/CD で型エラーが出る可能性
1ヶ月以内	`target` / `module` の更新	設定変更のみで完了するケースが多い
7.0 リリース前	`outFile` からバンドラーへの移行	アーキテクチャ変更を伴うため時間が必要
7.0 リリース前	`import assert` → `import with`	構文の全置換が必要

まとめ: 6.0 は「移行税」、7.0 は「配当」

TypeScript 6.0 の破壊的変更は確かに面倒です。しかしこれは、7.0 で得られる10倍のビルド速度と3倍のメモリ削減への投資と考えるべきです。

私のポジションは明確です。ignoreDeprecations に逃げず、6.0 のうちに非推奨オプションをすべて排除すべきです。理由は単純で、6.0 なら非推奨警告として「何が問題か」を教えてくれますが、7.0 では「設定ファイルが読めません」としか言ってくれないからです。

移行のコストが最も低いのは「今」です。プロジェクトの tsconfig.json を開いて、まず npx tsc --noEmit を実行してください。出てきた警告の数が、あなたのプロジェクトの「移行債務」です。