Introduction

In this article, I want to share my experience of upgrading Angular project with out-of-date and low maintainable code base. I will guide you through all preparations, steps, best practices and mistakes I found and made during the process. Also, I introduce some fun metrics for complex tasks.

Project description and history

My current project is the web app that has first commits about five years ago with frontend based on Angular.js. On Angular 2 RC release most important pages or completely new ones are developed using the second generation of the framework. So there are two apps that run on two different ports and a user simply navigates between them. E.g. you see a list of entities on a new Angular app but on row click you are redirected to details view on legacy Angular.js app. Having the same UI style guide brings a consistent look and feel.

With a rush of new features requests, the code base was not maintained properly in time and tech debt increased dramatically. No separate resources were allocated for keeping up-to-date libraries being used and general ecosystem. The only significant task was done is Angular upgrade to version 4. So when I joined a project about a year ago the state of a new Angular app was:

• Angular 4.3
• Angular Material 2 beta
• No Angular CLI, just some custom build tool instead, based on Gulp.js. As a result, two key optimization approaches like Ahead-of-Time compilation and lazy loading modules were not applied.

The main goal of the upgrade was not just changing Angular version from 4 to 6, but the upgrade of Angular ecosystem, improve initial application load speed and have the latest Material library with completely new components and extended functionality of existing ones. And one risky item was that LTS of version 4 was ending soon.

Where to start

Angular team created a useful Angular Update Guide. Just select current and target version, app complexity and you will see check-list of tasks to be done. This will create some preliminary plan and help to avoid tricky issues in advance instead of “stackoverflowing” numerous build/lint/runtime errors. At the moment of the upgrade was started the latest Angular version was 6.0.7.

Before I started I set three rules for myself:

• Make granular commits, commit changes after any sub-task is done. This will help to better track all changes and easily share results in future. All these commits are highlighted below with ✔️COMMIT✔️.
• Don’t do any additional refactor or fixes, even if it looks easy and obvious, only Angular upgrade related changes. Otherwise, one can be lost in finding problem root cause, was it upgrade or refactor.
• When I face some minor error that takes me more than 5 minutes to solve or investigate I will comment that code (if possible) and add specific to-do comment (e.g.TODO: Angular upgrade) to come back later and easily find and resolve instead of wasting time on early phases of the upgrade. Custom code snippet with this comment will be useful.

To have some metrics for upgrade sub-task I introduce MoJoR (Monkey Job Rating) with the value from 🐒 to 🐒🐒🐒🐒🐒. This rating will reflect time consumption and monotonous work. Every sub-task will have MoJoR value in paragraph title.

1. New project🐒

The first step was a complete replacement of project folder content with a newly CLI-generated project, but keeping existingsrc folder. As a result, there are out-of-date app files within the latest Angular engine. Definitely, this won’t even build but at least we have the foundation to start upgrading app files. From this point, we can observe the evolution of app modules, components, templates and services. Feeling optimistic and ✔️COMMIT✔️.

2. Make it build🐒🐒🐒

My first aim was to make application at least buildable. First of all, I generated a checklist from the upgrade guide, selected “Advanced” app complexity and went through items one by one. Two major items of current sub-task are described below, the rest were a couple of minor issues. On such global things like upgrade to latest RxJS 6 and switching to HttpClient I worked a bit later. Also in Angular CLI generated project default Typescript lint rules were more strict in comparison to rules we already had. So I postponed Typescript linter errors fix too.

RxJS (phase 1)🐒

Angular 6 comes with a new version of RxJS 6 that has breaking changes. But there is a special compatibility package that will help to postpone resolving this version change. So I installed it temporarily without saving in package.josn. More info about RxJS changes one can find in the video below:

Material🐒🐒🐒

Another big amount of build errors were related to Angular Material. Beta version uses legacy prefixes ( mdinstead of mat). So careful bulk change will help: element tags, directives, CSS class names, modules and components names.

The rest of build errors were caused by some deprecated/renamed properties/methods/directives of Angular or Material. Another source of issues could be some specific code related to custom Gulp.js based build tooling. E.g. in all decorators of components classes it was necessary to make the following changes:

• removed explicit module definitions moduleId: module.id
• in style file paths changed the file extension from css to scss.

So after changing almost every application file (about 600), I managed to build and launch the application 🎉. Feeling happy and ✔️COMMIT✔️.

3. HttpClient🐒🐒🐒

The next step was to move to modern HttpClient:

1. Replace imports of all Http module related stuff with HttpClient module
2. Remove all calls of json() method of response object as it is already JSON by default
3. Refactor building of URL query parameters. Prior to HttpClient simple strings concatenation was used. But with a new client I started to use new immutable HttpParams object

This may look a bit overcomplicated but building queries became more strict and clear to understand. Feeling confident and ✔️COMMIT✔️.

4. RxJS (phase 2)🐒🐒🐒🐒🐒

Then it was the right time to get rid of old RxJS 5:

1. Now delete rxjs-compat package that was installed earlier
2. Delete separate file with all Rx operators (was considered as best practice in RxJS ≤ 5)
3. Go through almost every component class, service, directive and wrap all RxJS operators in pipe() operator and rename operators with changed names in version 6.

This was defenitely the most monotonous piece of work. Feeling bored and ✔️COMMIT✔️️.

5. TSLint 🐒🐒🐒

To make the code more safe and standardized it was necessary to turn on default TSLint rules and fix corresponding errors. Also, I added application prefix to angular.json, so this prefix was added to all custom components. Feeling refreshed and ✔️COMMIT✔️️.

6. Lazy load🐒

The application has about ten feature modules, so it was not a big deal to change routings. Size of the main bundle was decreased. As a result, if a user opened app just to check dashboard or some notifications, the rest heavy functionality was not loaded. Feeling fresh and ✔️COMMIT✔️️.

7. Ahead-of-Time Compilation🐒🐒

Originally fixing AOT compilation errors was estimated for about one day. Earlier there was no possibility to run it and it was considered that codebase has a lot of related errors. But in fact, the number of errors was minimal. In an hour of fixing I have finally achieved the main goal of upgrade that can be clearly measured, AOT compiled application with the initial load of about 2 seconds 🎉. Feeling blessed and ✔️COMMIT✔️️.

8. Bonus: Lodash🐒🐒

Lodash is used in the project. I’m not a big fan of such libraries and agree with this article. Anyway, it looked like there was some space for optimization by importing operators in a better way. I created a separate file with only those Lodash operators that are used in the app (similar approach as in RxJS ≤ 5). Afterwards simply replaced import path and refactored usage of chainoperator. Also, I blacklisted direct imports from lodash in tslint.json.

With a help of Webpack Bundle Analyzer I can clearly see results of optimization:

• full Lodash import 711 KB
• selective Lodash import 184 KB

“Gzipped” difference is only about 30 KB. Frankly speaking, I’m not sure if this can be really called “optimization”. And at the moment of writing this article, separate file with operators looks an over-engineering and extra work. Especially for unit tests, where I did not manage to include this file during the test run of Karma. Anyway, a bad experience is still experience. And there can be cases and projects where size decrease of the main bundle by 30 KB will be a significant improvement.

Feeling good and ✔️COMMIT✔️️.

9. Upgrade to latest minor version🐒

In a meantime of upgrade process, a couple of minor versions of Angular were released. So the final chord was upgrading the application to the latest minor version 6.1.1. And in this case, the upgrade was done easily in a one minute with a help of CLI commandng upgrade. The result was modified package.json, no other changes were required. This was the last development step. Feeling accomplished and ✔️COMMIT✔️️.

Results sharing

The last but not least was sharing results of this huge amount of work (and paid work hours) with a team and customer. Naturally, each of them will be interested in different aspects of the upgrade.

For the rest frontend engineers, I made a small demo. I walked them through every commit to show the evolution of code.

Also, there was some information to share with QA engineers. We do not use Protractor. Automation QA team uses Python-based test framework for E2E testing. So with Material library upgrade a lot of XPath locators became invalid, in most cases due to prefix change (md to mat). So I provided QA engineers with a commit URL that has code diffs related to the Material upgrade. This simplified their work as they could analyze code changes that affected tests and easily fix them.

And with product owner I shared and demonstrated the following results:

• Initial load time of application decreased. More details in performance profiling summary charts:

• In future with new feature modules being added initial load time won’t be affected due to the usage of lazy loaded modules.
• The latest Material library has more components we can use so there will be no need of creating new ones from scratch that is time-consuming. Also, existing components received more customization and functionality.
• LTS of new project’s framework version ends in November 2019.
• No critical issues were found after releasing the app with upgraded Angular. And this was achieved mainly by adding AoT compilation and step-by-step upgrade.

Conclusion

This was an interesting task that helps to understand Angular ecosystem better, how it evolved, and in general great experience of making complex system up-to-date. There is a nice Ukrainian word “перелопатити” that means something like “go through with a shovel”, that exactly characterizes what was done.

One can be curious about unit tests. There is a dozen of them. But they were not been maintained even before the upgrade. So this is the task for future sprints. Anyway, the process of the upgrade will be the same.

At the moment of the article being written Angular 7 has been released. And now with a help of Angular CLI future upgrades will be definitely less painful and with MoJoR 🐒.