Open1

Angularのアップデートに関するメモ帳

kazumasakazumasa

Angularの「ng update」の基本的な使い方と、バージョン18から19へアップデートする際の注意点について調査します。

「ng update」の基本コマンドや、使用方法の詳細、依存関係の管理方法について解説します。
また、Angular v18からv19へアップデートする際の推奨手順や、変更点、互換性に関する注意点、エラー対処方法などを整理してお伝えします。

調査が完了したら、詳細をお知らせします。

Angularの「ng update」コマンドの基本とAngular v18からv19へのアップデート

ng updateコマンドの基本的な使い方

ng updateとは: Angular CLIのng updateコマンドは、プロジェクトの依存パッケージを最新バージョンにアップデートし、必要に応じてコードの自動変換（マイグレーション）を行うためのコマンドです (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。特にAngular本体（@angular/coreや@angular/cli）をメジャーバージョンアップする際に利用され、単にパッケージを更新するだけでなく非推奨APIの置き換えや設定ファイルの更新なども自動的に実施します (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。これにより、開発者は手作業の修正を最小限にAngularの最新機能を取り込むことができます。

主なコマンド例: 一般的にAngularを最新の安定版にアップデートするには、プロジェクトのルートディレクトリで以下のように実行します（Angular CLI自体とフレームワークコアを同時に指定します） (ng update • Angular 日本語版):

ng update @angular/cli @angular/core

上記コマンドは、現在のプロジェクトをAngularの最新安定版まで一括更新します (ng update • Angular 日本語版)。特定のメジャーバージョン（例えばv19）へアップデートしたい場合は、パッケージ名にバージョン範囲を指定します (ng update • Angular 日本語版)。例えばAngular 19系へ更新するには次のように実行します。

ng update @angular/cli@^19 @angular/core@^19

※この例では最新の19.x.x系に更新します (ng update • Angular 日本語版)（@latestタグ指定や^19指定により、19系の最新パッチ版が適用されます）。

主要なオプション: ng updateにはいくつか便利なオプションがあります。主なものを以下にまとめます。

オプション 説明
--next 次のベータ版やリリース候補（RC）版にアップデートします (ng update • Angular)。
--allow-dirty Gitリポジトリに未コミットまたは未管理の変更があってもアップデートを許可します (typescript - Repository is not clean. Please commit or stash any changes before updating In Angular 8 - Stack Overflow)（通常、**「リポジトリがクリーンでない」**エラー回避に使用）。
--force ピア依存関係のバージョン不整合を無視して強制的にアップデートします (typescript - Repository is not clean. Please commit or stash any changes before updating In Angular 8 - Stack Overflow)（依存関係の制約でブロックされる場合に使用。ただし副作用に注意）。
--create-commits (-C) アップデートやマイグレーションごとにGitコミットを自動作成します (ng update • Angular)。変更履歴を追跡したいときに便利です。
--migrate-only パッケージのバージョンは変更せず、マイグレーションスクリプト（コード変換）のみ実行します (ng update • Angular)。--from/--toオプションと併用して特定バージョン間の変換だけを適用できます。

使用する場面: ng updateは、Angularのフレームワーク自体やAngular CLI、Angular MaterialなどAngular公式パッケージを新しいメジャー/マイナー版に上げるときに主に使います。例えば「Angular 18から19へ上げたい」「Angular 18.xの最新パッチに上げたい」といった場合です。加えて、Angularと連携する一部のサードパーティライブラリ（NgRxやAngular Firebaseなど）もng update用のスケマティックを提供している場合があり、その際は同様に ng update パッケージ名 で対応するライブラリのアップデートと自動修正を行えます。通常、メジャーバージョンアップや重要なマイナーアップデートではng updateによる自動移行が推奨されており、パッチレベルのアップデート（バグ修正のみ）では単純な依存関係更新でも問題ない場合があります (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia) (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。

依存関係の更新とマイグレーション: ng updateを実行すると、該当パッケージ（例: @angular/core）およびそれに関連するパッケージ群をまとめて更新します (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。例えばAngular本体を更新する場合、@angular/coreだけでなく@angular/commonや@angular/compiler、必要に応じてrxjsやzone.js、TypeScriptのバージョンまで含めて適切な組み合わせにアップデートされます (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia) (Version compatibility • Angular)。さらに、アップデート時には自動的にマイグレーションスクリプトが実行され、古いバージョンで非推奨になった設定やコードが新しい書き方に置き換えられます (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。たとえば、angular.jsonから不要になった項目を削除したり、将来的に削除される予定のAPI呼び出しを新しいAPIに書き換えるといった処理が行われます (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。この自動マイグレーションによって、開発者は手作業での大規模な書き換えをせずに安全にアップグレードできます。なお、ng update実行後には変更点の差分を確認し、アプリケーションが正しく動作するかテストすることが重要です (AngularプロジェクトのためのRenovate設定 | lacolaco's marginalia)。

よくあるエラーと対処法: ng updateコマンドを利用する際に遭遇しやすいエラーとその対処法をいくつか紹介します。

  • 「Repository is not clean (リポジトリがクリーンでない)」エラー: アップデート実行時に未コミットの変更があると、このエラーで処理が停止します。対処法は変更をコミットまたはスタッシュしてから再実行することです。どうしてもコミットせずに進めたい場合は、上記の--allow-dirtyオプションで強行できます (typescript - Repository is not clean. Please commit or stash any changes before updating In Angular 8 - Stack Overflow)が、アップデート後に問題が発生しないか十分注意してください。

  • ピア依存関係の競合によるエラー: 特定のライブラリが要求するAngularのバージョン制約に抵触する場合、ng updateがブロックされることがあります（例：「requires a peer of @angular/core <18 but 19 found」のようなメッセージ）。この場合、まずそのライブラリ（またはその新バージョン）がAngular最新版をサポートしているか確認しましょう。対応版が存在するなら一緒にアップデートし、不明な場合一時的に--forceオプションで強制アップデートする方法もあります (typescript - Repository is not clean. Please commit or stash any changes before updating In Angular 8 - Stack Overflow)。【※注意】--forceでの強制アップデート後は、該当ライブラリが正常に動作するかテストし、必要なら代替ライブラリへの移行を検討してください。

  • グローバルCLIのバージョン不一致: 開発マシンにグローバルインストールされたAngular CLIのバージョンと、プロジェクト内のCLIバージョンが大きく異なると、コマンド実行時に警告が出たり不整合が生じることがあります。アップデート前後にはグローバルのAngular CLIも最新に更新しておくことが推奨されます（例: npm install -g @angular/cli@19 等）。こうすることでローカルプロジェクトとコマンドの互換性を保てます。

  • その他のエラー: アップデート途中でネットワークエラーやメモリエラーが起きた場合、再度ng updateを実行すれば途中から続行されます。依存関係解決の不具合で失敗する場合は、一度node_modulesを削除してnpm installし直す、npm cache cleanするなど環境を整えてから再挑戦してください。アップデート完了後にビルドエラーが発生する場合は、CLIが出力したBreaking Changes（破壊的変更）に関するメッセージやAngular公式の変更ログを確認し、それに従ってコード修正を行います。例えば、Angularのアップデートに伴い型定義が厳密化されてエラーになった場合は型注釈を追加する、不要になったpolyfillsのインポートが削除された場合はコードから参照を外す、といった対応をします。

以上がng updateコマンドの基本的な使い方と注意点です。次に、具体的にAngular v18からv19へのアップデート手順と変更点について詳しく見ていきます。

Angular v18からv19へのアップデート

推奨されるアップデート手順

Angular v18からv19へバージョンアップする際は、以下の手順で進めることが推奨されます。

  1. 公式情報の確認とバックアップ: まずAngular公式のリリースノートやアップデートガイドを確認し、変更点や注意事項を把握します。重要なプロジェクトであれば事前にソースコードのバックアップやGitブランチの作成を行い、いつでも元の状態に戻せるようにしておきます。

  2. Angular CLIの更新: 開発環境にインストールされているAngular CLI（グローバル）を最新バージョン(v19系)に更新します。例えばnpmを利用している場合、npm install -g @angular/cli@19 を実行します（Linux/macOS環境では先頭にsudoが必要な場合があります）。これにより、新バージョン用のコマンドが利用可能になります。

  3. プロジェクトの依存関係更新: プロジェクトディレクトリに移動し、Angular本体とCLIをv19へアップデートします。具体的には以下のコマンドを実行してください (Guide to update your Angular application v18.0)。

    ng update @angular/core@19 @angular/cli@19

    CLIが新バージョンのパッケージをインストールし、続いてマイグレーションスクリプトが自動的に走ります。実行中にいくつか質問プロンプトが表示される場合があります。内容を確認し、必要に応じてYes/Yで変更を適用してください。（※ヒント: エラーが発生した場合は前述の対処法セクションを参照してください。）

  4. 関連パッケージの更新: Angular MaterialやAngular CDK等、Angular公式の追加ライブラリを利用している場合は、対応するv19版へアップデートします。例えばMaterialを使っている場合、上記コマンドに続けてng update @angular/material@19 @angular/cdk@19を実行します。その他、フォームや言語サービスなど個別にインストールしているAngularパッケージ（例: @angular/formsや@angular/localize）があれば、それらもpackage.jsonのバージョンを確認し必要に応じて更新してください。RxJSについては、Angular 19はRxJS 7系との後方互換を保ちつつ、RxJS 8もサポートしています (Version compatibility • Angular)。RxJS 8を利用したい場合はnpm install rxjs@^8で手動更新できますが、既存コードとの互換性に注意してください。

  5. ビルドとテストの実行: 依存関係の更新が完了したら、ng serveやng buildでアプリケーションが正しくビルド・起動できるか確認します。併せてng testで単体テストがすべて通ることを確認してください。特に大きな変更があった部分（後述の変更点を参照）の周辺は重点的に動作確認します。

  6. 追加のマイグレーションや手動修正: Angularアップデートによって非推奨APIの置換などは自動で行われますが、新しい推奨手法への移行がオプショナル（任意）になっている箇所もあります。例えば、v19で安定版となったSignalベースの@Input/@Outputやクエリにコードを書き換えたい場合、以下の専用スクリプトを手動で実行できます (Meet Angular v19. In the past two years we doubled down… | by Minko Gechev | Angular Blog) (Meet Angular v19. In the past two years we doubled down… | by Minko Gechev | Angular Blog)。

    # @Input()をSignalベースのInputに変換
ng generate @angular/core:signal-input-migration

# @ViewChild等のクエリをSignalベースに変換
ng generate @angular/core:signal-queries-migration

# 従来のEventEmitter出力を新しい出力APIに変換
ng generate @angular/core:output-migration

    上記は必要な場合のみ実行します。また、アップデートガイドに「手動で対応が必要」と記載された項目（Breaking Changes）があれば、その指示に従いコード修正を行ってください。作業が完了したら改めてビルド・テストを行い、アップデート前と同じ機能が正常に動作することを確認しましょう。

Angular v19の主要な変更点と新機能

Angular 19は、開発者体験とパフォーマンスの向上を主眼に、数多くの新機能や改良が盛り込まれています (Meet Angular v19. In the past two years we doubled down… | by Minko Gechev | Angular Blog) (Meet Angular v19. In the past two years we doubled down… | by Minko Gechev | Angular Blog)。v18からv19へのアップデートで特に注目すべき主要ポイントをまとめます。