Angular 14.1新規プロジェクトのTypeScriptエラー

問題概要

Angular CLI (v14.1) で新規プロジェクトを作成後、npm install 実行時に次のTypeScriptエラーが発生します：

// エラーメッセージの例
node_modules/@types/node/stream/web.d.ts:484:13 - error TS2502: 
'ReadableByteStreamController' is referenced directly or indirectly in its own type annotation.

この問題は主に以下が原因で発生します：

1. @types/node のバージョン非互換
2. Node.js環境とのバージョン不一致
3. TypeScript型チェックの循環依存問題

エラーが発生するとプロジェクトのビルドが失敗し、開発サーバーの起動も不可能になります。

注意点

この問題は特にAngular 14プロジェクトで顕著ですが、Angular公式ではv14のアクティブサポートは2023年11月に終了しています。長期的な解決策としてバージョンアップグレードを検討しましょう。

根本原因

Angular 14は次の環境に依存します：

Angular 14 → TypeScript 4.7.x → Node.js 14.15+ or 16.10+

しかし新規プロジェクト生成時、@types/node パッケージが最新バージョン（例: v20.3.2）でインストールされると、定義ファイルweb.d.ts内で型の循環参照が発生します。

解決方法

方法1: @types/nodeのバージョン固定（推奨）

1. package.json を開く
2. devDependencies セクションを以下のように修正：

{
  "devDependencies": {
    // 他パッケージはそのまま
    "@types/node": "^16.18.50", // 互換性のあるバージョンに変更
    // 他のdevDependencies...
  }
}

3. キャッシュをクリアして再インストール：

rm -rf node_modules package-lock.json
npm install

動作原理

^16.18.50 と指定することで、Angular 14と互換性のあるNode.js型定義（v16系列）を使用します。このバージョンは循環参照問題を回避します。

方法2: Node.jsバージョンの変更

Angular 14がサポートする公式Nodeバージョン：

• 14.15.0以上
• 16.10.0以上

現在のNode.jsが上記範囲外の場合、バージョン管理ツール（nvmなど）で変更：

# Node v16.20.0をインストールして使用
nvm install 16.20.0
nvm use 16.20.0

# インストール確認
node -v  # v16.20.0と表示されることを確認

Angular公式バージョン互換表で常に最新情報を確認してください。

方法3: TypeScriptの型チェック回避（一時的対策）

tsconfig.json にコンパイラオプションを追加：

{
  "compilerOptions": {
    // 既存のオプション...
  },
  "angularCompilerOptions": {
    "skipLibCheck": true
  }
}

注意

この方法はエラーを無視するだけの一時的対策です。本質的な解決ではなく、依存ライブラリの型チェックをスキップするため、他の潜在的問題を見逃すリスクがあります。

補助的対策

npm ci で厳密インストール

ロックファイル（package-lock.json）がある場合、コマンドを変更：

npm ci  # package-lock.jsonに基づく厳格なインストール実行

npm ci は互換性のない依存関係の更新を抑制します。

依存関係ツリーの調整

不要に新しいバージョンが導入されていないか確認：

npm list @types/node  # インストールされたバージョンを確認

予防策

1. プロジェクト生成時のバージョン指定：

ng new --package-manager=npm --strict=false

2. ロックファイルコミット： package-lock.jsonをリポジトリに常に含める
3. 定期的な依存関係更新：

npm outdated  # 互換性チェック

結論

Angular 14プロジェクトのTypeScriptエラー解決には：

1. 🎯 優先解決策: @types/nodeを^16.18.50に固定
2. 🔧 環境調整: Node.jsをv16系列に変更
3. ⚠️ 一時的回避: skipLibCheck（最終手段）

プロジェクトの安定性を確保するため、Angularと依存パッケージの公式バージョン互換性を定期的にチェックし、中期的にはAngularバージョンのアップグレードを検討してください。