Angular Version Update Journey : Angular v10 to v14

Recently, I had the opportunity to upgrade a legacy Angular application from Angular 10 to Angular 14. This document outlines the lessons I learned during the update process. Before proceeding, I strongly recommend reviewing the official Angular update documentation at https://update.angular.io/?l=3&v=10.0-14.0. According to this official document, it’s advisable to update version by version.

The following steps will be covered in this article:
1. Analysis
2. Update
3. Compilation Errors, Issues, and Solutions
4. Validating the Updated Version through the Browser
5. Conclusion

Analysis Required for the Update:

The initial step involves carefully reading the documentation and understanding the required changes for your application. Once you grasp the necessary code modifications, you can initiate the update process.

1. Analyze which peer dependencies are deprecated or no longer maintained and require updating. For instance, in my case, the library “@agm-core” was deprecated, and another library “angular-user-idle” supported all Angular versions except 11.
2. Examine the code affected by the “ng update” command and identify which code changes need to be made manually. In our case, we were using Angular Material themes (https://material.angular.io/guide/theming), and some functions were deprecated and had been renamed to entirely different names. Other changes will be discussed further.
3. Plan for unit testing and regression testing to identify any breaking changes in the application following the update.

Update Process:

With the analysis complete, let’s move on to the update process.
Since we are transitioning from v10 to v14, the Angular update guide recommends updating version by version. Therefore, we’ll go through updates to versions 10, 11, 12, 13, and finally 14.

Step 1: Ensure you have the required Node.js and NPM versions. Refer to the version compatibility guide to find the suitable Node.js version for your needs. Attempting to run the “ng update” command with a Node.js version lower than v14 may result in the following error:

Node version needs update

/*Solution for updating node*/
sudo npm install -g n

Step 2: Once the correct Node.js versions are installed, commence the update process by running the commands outlined in the update guide:

ng update @angular/core@11 @angular/cli@11 

Step 3: Depending on peer dependencies and dev dependencies, the above update command will provide feedback. Follow the provided feedback.
To resolve devDependencies and peerDependencies, review each dependency on the npm website and align their release dates with the Angular version you are using. Note that if resolving devDependencies and peerDependencies requires changing the version of “angular/core” or “angular/cli” to v11, you must uninstall unsupported dependencies and reinstall them after the update.
Step 4: After resolving dependencies, repeat Step 2 until the update is complete on all the dependencies.

Once the upgrade is finished, attempt to run the project using “npm start.” Address any compilation errors arising from the update. Refer to the Compilation Errors section for guidance.

Compilation Errors, Issues, and Solutions:

• Functions: If you utilize locale data arrays, be aware that this API now returns read-only arrays. If you were modifying them (e.g., using “sort(),” “push(),” “splice(),” etc.), your code will no longer compile. If you need to modify the array, make a copy (e.g., using “slice()”) and modify the copy.
• Decorators: The “@Effect” decorator is deprecated. Update your code to use “createEffect()” instead.
• Pipes: The async pipe no longer assumes that an input typed as undefined will return undefined; it actually returned null for undefined inputs. The date pipe now explicitly states its accepted types, and the number pipes (decimal, percent, currency, etc.) also explicitly list their accepted types. The slice pipe now returns null for an undefined input value, aligning with most pipes’ behavior. Make necessary changes.
• Until Angular 12, “MatProgressButtonsModule” only needed to be replaced with “MatProgressButtonsModule.forRoot()” to address runtime errors in the console. (Reference: https://stackoverflow.com/questions/70376940/no-provider-for-injectiontoken-global-config-error) However, in version 14, the library was no longer maintained and had to be replaced with in-house code.
• Some libraries may not support specific Angular versions. In such cases, you can temporarily add “ — legacy-peer-deps” to the npm install command.
  e.g.,: “npm install –legacy-peer-deps”. This will force the installation.
  For instance, the “angular-user-idle” library supports all versions except 11. You can force the installation and then add it again during subsequent updates.
• The “themes.css” file contains deprecated Angular/Material functions that lead to compilation issues. Replace these deprecated functions with the current functions provided by Angular/Material for the same purpose.
  Examples of these changes include:

Voila, You Are Done With Your Update Successfully!

You’re now prepared to run “npm start” and test your application for any disruptions.
If you have unit tests, ensure you address any failing tests.

Validating Your Update:

To validate that the dev console displays the correct version, follow these steps:

• Press F12 in your browser.
• Navigate to the “Elements” tab of the Developer Tools menu.
• In the top section, find the “<body>” tag and expand it.
• Under the “<body>” tag, locate the “<app-component>” tag.
• Within that tag, there should be an “ng-version” attribute displaying the current Angular version (looking for version 14 or higher).

Validating your update is successful on higher environments

Conclusion:

Updating Angular is a complex process that requires careful analysis. Failing to analyze tasks thoroughly can result in update-related issues.

Last, but not the least — I would like to add my two cents on how this update can be done in an agile setup.
I would suggest creating an epic named Angular Update v10->v14.
Under the epic you can create stories, and every story might have some tasks to complete.
Below is a simple example of the same:

Epic — Angular Update v10->v14
Stories:
SPIKE/Analysis -Read the guide and find out code changes needed in your project after update using following reference points:
Point 1: Make a list of those changes, create a story to update and AC to system test those touched flows.
Point 2: Analyze package.json for devDependencies and peerDependencies , and find out which dependencies are changing. Angular-Google-maps, MatProgressButtons, Angular Material, Karma test, lint, puppeteer, lighthouse etc. Each will need a separate story to be addressed.

Based on the list above, create a separate story for each and write ACs for the same and provide estimations accordingly.
Example: Based on the list in Point 1 and 2, stories can be as follows:

1. Run the update process and resolve compilation errors
2. Ensure unit tests are working
3. Ensure linting is working
4. Ensure angular-google-maps is implemented correctly
5. Ensure puppeteer is implemented
6. Regression testing
7. Performance testing
8. If you are using CICD or managing servers, there should be a story to deploy the updated version of Node and Npm to the servers and the updated commands for smooth deployment.

Thanks for reading!!