Angularのメジャーバージョンアップ事前調査

Angular の EOL 対応について、どのような手順を踏めばよいかをまとめる。

特に、クライアントに納品する視点で、本番のエラーリスクを考えた事前準備などにフォーカスしているため、個人で自分用アプリを開発している方は、アップグレード実施手順から参照のこと。

事前知識

まずは、事前に押さえておきたいポイント。

依存関係について

  • Angular のアップデートに伴い、Node.js のアップデートも必要となる。
  • Node.js は Angular と異なり、アプリケーションではなく、ビルド環境（ローカル PC またはサーバーなど）に紐づくアップデートである点に注意する。
  • Angular のアップデートに伴い、package.json で記述している使用パッケージ（依存パッケージ）もアップデートされる。

何を確認するのか？

Angular は画面資源を作るフレームワーク、すなわち CSS と TypeScript の確認をすればよいのだと、安易に考えがちだが、もう一段階深く理解しておく。

そうすることで、このフレームワークは CSS 観点、このフレームワークはルーティング観点、というように、リリースノートのどこを読めばよいのかや、必要なテストを絞り込み、リスクを考えやすくなる。

Angularのチェックポイント

Angular は、あくまでコンポーネントやデータバインディング、ルーティングなど、アプリケーション構造を制御するフレームワークである。

Angular 自体は CSS の仕様や描画エンジンには手を加えておらず、CSS の出力や解釈に直接変更を加えることはない。

※ ビルド方式や View Encapsulation、ngClass / ngStyle の仕様変更が稀に影響することがあるため、このあたりはリリースノートを注視する。

しかし、高確率で ngx-bootstrap など、CSS を扱う UI ライブラリのアップグレードを伴うため、
結果として CSS の確認も必要となる。

CSS の確認の難しさ

いずれかのパッケージアップデートによりCSS の仕様に変更があった場合でも、ビルド時にエラーになることはない。

ロジックではないため、システムが止まるような致命的なエラーになることはない反面、検知することが難しい。

先ほど少し触れた ngx-bootstrap のリリースノートは、特に丁寧に確認する必要がある。

テストについては、現在はキャプチャを前後比較してくれるPlaywright のような無料のフレームワークもあるため、これらの利用を検討する。

参考：playwright基礎

アップグレードの特性

Angularアップグレードの特性

Angular のアップグレードは、複数のメジャーバージョンをまたぐことはできない。

つまり、Angular を 13 から 16 にアップグレードしたい場合、以下のような手順になる。

  1. 13 → 14 にアップグレード ＞ ビルド & Lint チェック ＆ 単体テスト
  2. 14 → 15 にアップグレード ＞ ビルド & Lint チェック ＆ 単体テスト
  3. 15 → 16 にアップグレード ＞ ビルド & Lint チェック ＆ 単体テスト

また、Angular のアップグレードは、どれだけきれいにやろうとしても、たいてい依存関係のエラーが発生する。（後述）

1度で成功させようとせず、アップグレード後に依存関係を回復する方向で進めた方がよい。

Node.jsアップグレードの特性

Node.js のアップグレードは、Angular と異なり、複数のメジャーバージョンをまたいで
一気に実行できる。

Node.js は基本的に後方互換性を重視しているためである。

nvm を使用すれば、異なるバージョンを都度切り替えて環境を利用することもできる。

おおまかな流れ

  1. 必要なパッケージ（Node.js、Angular、依存パッケージ）のリリースノートを確認する
  2. Node.js のアップグレード ※複数バージョンをまたぐ場合でも一括でアップグレード可能
  3. Angular のアップグレード ※これに紐づいて、使用している依存パッケージもアップグレードされる
  4. ビルド & Lint チェック ＆ 単体テスト ※複数バージョンをまたぐ場合、3と4を交互に繰り返す
  5. 結合テスト（アプリケーションの動作テスト） ※特にCSSについてはPlaywrightなどを使用してキャプチャ現新比較を行う

リリースノートの確認方法

ここで、リリースノートの確認箇所や、大切なポイントについて触れておく。

リリースノートと一口に言っても何ページもあるし、依存パッケージだって数十個ある。ポイントを絞らないととてもじゃないが工数対効果に追いつかない。

確認は、メジャーバージョンアップのリリースノートのみでよい

破壊的変更は、基本的にメジャーバージョンアップでのみ行われるのが通例である。

そのほかの緊急の変更や、把握しておくべき仕様変更についても、メジャーバージョンアップのページに記載されるためである。

例えば、Node.js について、v16.0.0 のメジャーバージョンアップのリリースノートでは、15 系から 16 系へのアップグレード時の主な変更点が記載されている。

v16.22.22（LTS）のような最新版のドキュメントも存在するが、基本的に確認すべきなのはx.0.0 のドキュメントのみでよい。

LTSの範囲は？

LTS のドキュメントは、前回との差分を示したものに過ぎず、そのバージョンまでの累積の修正内容を記載したものではない。

つまり、16.22.23 → 16.22.25（LTS）の順でリリースされていたとすれば、この間の差分のみを示したものであり、16.0.0 → 16.22.25（LTS）の変更を示したものではない。

LTS のドキュメントは、障害対応などで直近の変更を把握するために参照するものであり、
アップグレードのように累積の修正内容を確認するためのものではない。

Angularのアップデートガイド

Angular は、リリースノートを確認しても良いのだが、それとは別に独自にアップデートガイドを提供しており、アップデートしたいバージョンの from / to を入力すれば、必要な修正点が一覧で表示される。

どのパッケージを確認する？

依存パッケージまで含めると、アップデートされるパッケージは膨大な数になるため、どこまで確認するかは決めの問題になる。

リリースノートを確認すべきパッケージは、基幹部分と UI 系、主に以下を押さえておきたい。

  • Node.js
  • Angular
  • ngx-bootstrap（そのほか UI 系パッケージがあればそれらも）

Node.js のリリースノートは、全体を詳細に読む必要はなく、さらっと確認すればよい。

Node.js の破壊的変更は、Notable Changes の一部として記載されるが、その多くは runtime に関するものである。

runtime の変更は、Node.js 本体の実行環境や内部仕様の変更であり、通常のアプリケーションコードに直接影響することは少ない。

仮に影響があったとしても、多くの場合はビルド時にエラーとして検知される。

runtime 以外の修正で、「ソースコードに影響しそうだ」と思われるものがサラッと見て見つかれば、アプリ内で grep し、実際に使用していないことを確認する程度でよい。

Angular および ngx-bootstrap については、がっつり確認が必要。

上記 3 つのいずれにも当てはまらないものや、ngx-bootstrap 以外の UI パッケージについては、メジャーアップデートがある場合に軽く目を通す程度で問題ない。

ドキュメントから事前に修正箇所を考慮すべきか？

一般的には、事前にすべての準備や修正を完了させるのではなく、実際にアップグレード（ng update など）を実施したうえで、Lint やビルドの警告・エラーに一つずつ対応していく方法が、現実的かつ効率的。

リリースノートを網羅しようと、血眼にならないこと。

  • アップグレード前には、どこで何が問題になるか予想しきれないことが多い。→ ライブラリやフレームワークの更新内容、　プロジェクト独自の実装によって影響範囲が異なるため。
  • アップグレードコマンド（ng update）で自動修正される部分も多い。→ 手作業で修正する前に、自動マイグレーションを活用した方が効率的。
  • Lint やビルドの警告・エラーが、「対応が必要な箇所」を具体的に教えてくれる。→ 実際にアップデートしてみて初めて、対処すべきポイントが明確になる。

アップグレード実施手順

ここからは事務的な操作になるため、黙々と作業する。

Node.js のアップグレード

自由にバージョンを切り替えられる nvm の使用を推奨する。

nvm の使用方法については『Node.js+Angular備忘録＞Nodeバージョン管理』を参照。

nvmを使わず地道にアップグレードする場合は以下。

npm install -g npm@9

バージョン確認

npm -v

Angular のアップグレード

Angular のアップグレードを実行する。

npx ng update @angular/core@13 @angular/cli@13

※ ローカルに未コミットの修正があるとエラーになるため、完全に修正を元に戻すか、事前にコミットしておく必要がある。

package.json、angular.json、tsconfig については、必要なバージョンを満たすように、記述内容が自動で更新される。

ただし、この自動更新が動かないパッケージが多く、その場合はエラーとなり、package.json のdependenciesに記載しているバージョンを手動で書き換える必要が出てくる。
※後述の「アップグレード時のエラー」を参照すること

修正後、アップグレードが正常に完了したら、バージョンを確認する。

npx ng --version

アップグレード時のエラー

大抵、以下のようなエラーが発生する。
以下はAngular12から13にアップグレードを実行した際のエラー

Updating package.json with dependency @angular/router @ "13.4.0" (was "12.2.16")...
UPDATE package.json (3177 bytes)
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: hozen-web-front@0.0.398
npm ERR! Found: @angular/core@13.4.0
npm ERR! node_modules/@angular/core
npm ERR! @angular/core@"13.4.0" from the root project
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/core@"^12.0.0" from @fortawesome/angular-fontawesome@0.9.0
npm ERR! node_modules/@fortawesome/angular-fontawesome
npm ERR! @fortawesome/angular-fontawesome@"0.9.0" from the root project
npm ERR! Fix the upstream dependency conflict, or retry this command with --force
npm ERR! or --legacy-peer-deps to accept an incorrect (and potentially broken)
npm ERR! dependency resolution.

この例では、
@fortawesome/angular-fontawesome@0.9.0 が@angular/core@”^12.0.0″ を要求しているため、Angular が 13 系にアップグレードされた現在では依存関係エラーが発生している、という意味である。

実際に package.json を見ると、"@fortawesome/angular-fontawesome": "0.9.0" が指定されていた。

つまり、このパッケージをAngular 13 系に対応しているバージョンへアップグレードする必要がある。

npm install @fortawesome/angular-fontawesome@latest

コマンドで対応バージョンを調べる方法は無いため、ドキュメントを確認したところ、"@fortawesome/angular-fontawesome": "0.10.0" であれば対応していることが分かった。

package.json を上記の通り更新し、再インストールする。

npm install

上記の例のように、Angular のアップグレードに伴って依存パッケージも順次アップグレードしていく必要がある。

コメント

タイトルとURLをコピーしました