0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@fd_ai_teacher

TypeScript 7.0移行でハマった！Goベースコンパイラの新エラーと解決法

0
Posted at

TypeScript 7.0移行でハマった！Goベースコンパイラの新エラーと解決法

TypeScript 6.0から7.0へのバージョンアップで「突然ビルドが通らなくなった」「見慣れない型エラーが出た」と困っていませんか？特に、target: es5が使えなくなり、baseUrlが削除されたことで、既存プロジェクトのTypeScript 6.0/7.0移行は一筋縄ではいかないケースが多発しています。

この記事では、TypeScript 7.0でGoベースに刷新されたコンパイラがもたらす破壊的変更と、それに伴う具体的なエラー、そしてそれぞれの解決策をコード例とともに詳しく解説します。この記事を読めば、TypeScript 6.0/7.0移行時の主要な障壁を乗り越え、高速化された新しい開発体験を享受できるでしょう。

TypeScript 6.0/7.0への移行が必須となる背景：Goベースコンパイラによる革命

TypeScript 7.0は、コンパイラがJavaScriptベースからGoベースに書き換えられ、コンパイル時間が8〜12倍高速化されるという画期的なリリースです。Microsoftのベンチマークでは、VS Codeのビルド時間がTypeScript 6の125.7秒からTypeScript 7の10.6秒に短縮されたと報告されています。このパフォーマンス向上は、型チェック、出力、プロジェクト参照ビルドなど、多くの操作を並行して実行できるようになったGoベースのコンパイラの恩恵です。

TypeScript 6.0は、この7.0への橋渡しとなる重要なリリースとして位置づけられています。6.0で導入された多くの非推奨設定や破壊的変更は、7.0で完全に削除される機能への警告として機能します。そのため、TypeScript 7.0へのスムーズな移行には、まずTypeScript 6.0での変更点への対応が不可欠です。

TypeScript 6.0のインストール

まずはTypeScript 6.0をインストールし、移行の準備を始めましょう。

npm install typescript@6 --save-dev
# または最新の6.x系をインストールする場合
npm install typescript@next --save-dev

TypeScript 7.0のインストール

TypeScript 7.0は、以下のコマンドでインストールできます。

npm install -D typescript@latest

TypeScript 6.0/7.0移行で直面する主要な破壊的変更とエラー

Goベースコンパイラへの移行に伴い、TypeScript 6.0および7.0では多くの破壊的変更が導入されました。ここでは、特に開発者がハマりやすいポイントと、その解決策を具体的に見ていきます。

1. target: es5の削除と古いモジュール形式の非サポート

TypeScript 7.0で最も大きな変更点の一つが、target: es5の完全な削除です。これにより、ES2015が最小のコンパイルターゲットとなります。また、AMD, UMD, SystemJSといった古いモジュール形式もサポート対象外となりました。

ハマりどころとエラー例

既存のプロジェクトでtarget: es5を使用している場合、TypeScript 7.0に更新すると以下のエラーが発生します。

error TS5055: Cannot specify 'target' 'es5' when 'module' is 'esnext'.

回避策

  1. tsconfig.jsonのtargetを更新:
    targetオプションをes2015以上に設定します。最新のJavaScript機能を活用するためにはesnextやes2022などが推奨されます。 
    {
  "compilerOptions": {
    "target": "es2025" // または "esnext"
  }
}
  2. モジュール形式の更新:
    moduleオプションをesnext、nodenext、bundler、またはcommonjsに更新します。フロントエンドプロジェクトでバンドラを使用している場合はbundlerが適しています。 
    {
  "compilerOptions": {
    "module": "esnext" // または "nodenext", "bundler", "commonjs"
  }
}
  3. 古いブラウザのサポートが必要な場合:
    IE11などES2015をサポートしない古いブラウザを対象とする場合は、TypeScriptのコンパイルターゲットをes2015以上に設定し、Babelなどのトランスパイラを使用してES5にダウンレベル変換する構成を検討してください。

2. typesオプションのデフォルト変更による型定義の欠落

TypeScript 6.0からcompilerOptions.typesオプションのデフォルト値が空のリスト[]に変更されました。これにより、以前は自動的に含まれていたnode_modules/@types内の型定義（例: nodeやjestのグローバル型）が読み込まれなくなり、多くのプロジェクトで型エラーが発生する可能性があります。

ハマりどころとエラー例

processなどのグローバルオブジェクトや、jestのようなテストフレームワークの型が未定義として扱われます。

error TS2304: Cannot find name 'process'.

回避策

tsconfig.jsonのcompilerOptions.typesに、プロジェクトで使用しているグローバルな型定義パッケージを明示的に指定します。

{
  "compilerOptions": {
    "types": ["node", "jest"] // 使用するグローバルパッケージを列挙
  }
}

3. moduleResolutionの変更とbaseUrlの削除

moduleResolution: nodeやnode10がTypeScript 6.0で非推奨となり、7.0で完全に削除されました。また、baseUrlオプションも7.0で削除されています。これらはモジュールの解決パスに大きな影響を与え、相対パスの解決や絶対パスインポートに問題を引き起こす可能性があります。

ハマりどころとエラー例

モジュールのインポートパスが解決できなくなり、以下のエラーが発生します。

error TS2307: Cannot find module '...' or its corresponding type declarations.

回避策

  1. moduleResolutionの更新:
    moduleResolutionをbundler（バンドルツールを使用するフロントエンドプロジェクト）またはnodenext（Node.jsプロジェクト）に設定します。 
    {
  "compilerOptions": {
    "moduleResolution": "bundler" // または "nodenext"
  }
}
  2. baseUrlに依存していたパスの修正:
    baseUrlに依存していたインポートパスは、プロジェクトルートからの相対パスに書き換えるか、pathsマッピングを適切に設定し直します。 
    {
  "compilerOptions": {
    // ...
    "paths": {
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}
    ts5to6のような移行ツールがbaseUrlの削除とpathsエントリの書き換えを自動的に処理できる場合がありますが、現在のTypeScript 6.0/7.0移行に公式に推奨されているか、最新の移行ツールについては公式ドキュメントで確認が必要です。

4. TypeScript 7.0のプログラマティックAPIの欠如によるツールとの非互換性

TypeScript 7.0はGoベースのコンパイラですが、現時点では安定したプログラマティックAPIを提供していません。このため、typescript-eslint、ts-node、Vue/Svelte/Angularのテンプレートチェッカーなど、TypeScriptコンパイラのAPIに深く依存するツールは、TypeScript 7.0環境で正しく動作しない可能性があります。

ハマりどころとエラー例

該当するツールがTypeScript 7.0環境でエラーを報告したり、期待通りに動作しなかったりします。

回避策

  1. TypeScript 7.1を待つ:
    TypeScript 7.1で安定したプログラマティックAPIが提供される予定です。それまでは、これらのツールを使用する環境ではTypeScript 6.0を維持することを検討してください。
  2. サイドバイサイドインストール:
    package.jsonのエイリアス機能を使用して、CLIでの型チェックにはTypeScript 7.0を、APIに依存するツールにはTypeScript 6.0を使用するサイドバイサイドインストールを検討できます。 
    // package.json
{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2", // TypeScript 7.0を@typescript/nativeとしてインストール
    "typescript": "npm:@typescript/typescript6@^6.0.2" // TypeScript 6.0をtypescriptとしてインストール
  }
}
    インストール後、npx tsc --versionでTypeScript 6.0が、npx @typescript/native tsc --versionでTypeScript 7.0が報告されることを確認してください。

TypeScript 7.0の並列コンパイルを活用する

TypeScript 7.0のGoベースコンパイラの最大のメリットは、並列処理によるコンパイル速度の向上です。この恩恵を最大限に受けるための設定を紹介します。

並列コンパイルの利用

--checkersフラグで型チェックワーカーの数を、--buildersフラグでプロジェクト参照ビルダーの数を制御できます。CPUコア数に合わせて調整することで、さらなる高速化が期待できます。

npx tsc --checkers 8 # 型チェックワーカー数を8に設定
npx tsc --build --builders 4 # プロジェクト参照ビルダー数を4に設定 (モノレポ向け)

tsconfig.jsonの更新例（TypeScript 6.0/7.0向け）

これまでの変更点を踏まえたtsconfig.jsonの更新例を示します。

{
  "compilerOptions": {
    "target": "es2025", // TypeScript 7.0ではes2015が最小。モダンな環境ではes2025以上を推奨
    "module": "esnext", // モダンなモジュール形式を使用
    "moduleResolution": "bundler", // バンドルツールを使用する場合に推奨
    "strict": true, // TypeScript 6.0以降でデフォルトtrue。より厳密な型チェックを有効に
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["node", "jest"], // TypeScript 6.0以降でデフォルト[]のため、使用するグローバルパッケージを明示的に指定
    "rootDir": "./src", // TypeScript 6.0以降でtsconfig.jsonがあるディレクトリがデフォルトだが、明示的に指定を推奨
    "lib": ["es2025", "dom", "dom.iterable"], // 最新のJavaScript機能とDOM型定義
    "ignoreDeprecations": "6.0" // TypeScript 6.0で一時的に非推奨警告を抑制 (TypeScript 7.0では無効)
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

TypeScript 6.0/7.0移行のベストプラクティス

スムーズな移行のためには、以下のベストプラクティスを参考にしてください。

  1. TypeScript 6.0への段階的な移行:
    TypeScript 7.0に直接移行するのではなく、まずTypeScript 6.0にアップグレードし、そこで発生する非推奨警告やエラーを修正することが強く推奨されます。TypeScript 6.0は7.0への橋渡しとなるリリースであり、7.0で削除される機能の警告を発します。
  2. tsconfig.jsonの明示的な設定:
    strict、target、module、moduleResolution、types、rootDirなどの主要なコンパイラオプションは、デフォルトに依存するのではなく、プロジェクトの要件に合わせて明示的に設定します。これにより、将来のバージョンアップ時の予期せぬ挙動を防ぎます。
  3. --stableTypeOrderingの活用:
    TypeScript 6.0で--stableTypeOrderingフラグを有効にし、TypeScript 7.0との型順序の差異を事前に特定し修正します。TypeScript 7.0ではこの順序付けが常に有効になります。
  4. サイドバイサイドでのコンパイラ利用:
    typescript-eslintなどのツールがTypeScript 7.0の安定版APIをサポートするまでは、@typescript/typescript6パッケージ（または同様のエイリアス設定）を使用してTypeScript 6.0をAPI依存ツール向けに、TypeScript 7.0をCLIでの型チェック向けに共存させることが推奨されます。
  5. CI/CDでのテストの強化:
    移行中は、CI/CDパイプラインでTypeScript 6.0と7.0の両方でビルドとテストを実行し、互換性の問題を早期に発見します。
  6. 小規模な変更から開始:
    大規模なコードベースの場合、一度にすべての変更を行うのではなく、影響の少ない部分から段階的に移行を進めます。

まとめ

TypeScript 6.0/7.0への移行は、Goベースコンパイラによる大幅なパフォーマンス向上の恩恵を受けられる一方で、いくつかの破壊的変更に対応する必要があります。特にtarget: es5の削除、typesオプションのデフォルト変更、moduleResolutionとbaseUrlの変更は、多くのプロジェクトでエラーを引き起こす可能性があります。

この記事で解説した解決策とベストプラクティスを参考に、これらの障壁を乗り越え、TypeScript 7.0の高速な開発体験をあなたのプロジェクトにもたらしましょう。TypeScript 7.1で提供される安定したプログラマティックAPIにより、既存ツールとの互換性も改善される見込みです。最新情報は公式ドキュメントで随時確認するようにしましょう。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?