How to upgrade your Angular CLI project to Angular v7 (or v6) without too much manual pain

I recently upgraded a relatively big project to Angular and Angular CLI v7.
The instructions were the same as upgrading to v6. Except, for both versions there were missing pieces that I didn’t see fully documented in one place, and the most comprehensive docs I saw on how to do it involved more manual work than I liked, so, I decided to share my findings here for the next person.

Let’s upgrade…

Prerequisites

NPM

Before we continue, make sure to have latest NPM (at least 6.2). You can upgrade your NPM by running:

We’ll use the npx tool from NPM to run binaries from local and global packages as needed.
I don’t like installing the CLI globally, that’s why you’ll see me often run npx ng instead of just ng.

Angular v7 Or Angular v6

If for some reason you really want to upgrade to v6 first, replace latest below with something like ^6.0.0 and add a --to argument to ng update, but in my experience, going to v7 from v5 didn’t require this step.

ng update

This is the tool that takes care of upgrading all dependencies in package.json, and some breaking code changes between Angular versions.

It’s awesome, but it doesn’t do everything as we’ll see below.

Installing Latest Angular CLI

First, you need to install the latest Angular CLI locally before running ng update.
We cannot just run it with npx without install, because the global CLI always passes commands to the project specific version if applicable, so, to run the command, it needs to be locally installed.

There’s another missing dependency which might break the upgrade, and you’ll have to install it as well.

Later below you’ll run npx ng build to make sure everything else is alright. If it or ng update itself complain about missing packages, just add them. For example, my project required me to add date-fns for some reason to build.

Running The Update Command

The minimum you need is something like:

The --force is required to ignore peer dependency warning.
The --from must be the previous Angular CLI version you had before. Angular CLI can be confused without it.

If you have other libraries that support upgrading, and you probably do, the more generic form of above becomes:

See below for more about libraries.

Manual File Changes

Unfortunately the following files will have to be updated and merged by hand:

  • angular.json, from an existing .angular-cli.json or similar
  • tsline.json
  • src/polyfills.ts

Create a new project using the CLI, copy the files from that project, and then look in git diff or something to restore any customizations you might have, like styles / scripts / assets in angular.json, or uncommenting/restoring some import statements in src/polyfills.ts.

Remember to go to a different directory outside your project to create a new project to copy the files from.
The command for creating new project without installing the CLI is:

RxJS Automatic Upgrade

That’s another one where order of steps is important.

First, you need to install these 2 packages:

Then import the compatibility package in your code, so that the app still compiles, as it’ll be broken with RxJS upgraded to v6+. Add the following line at the end of src/main.ts.

Then, automatically convert all files to the new RxJS syntax:

Note that this command might take LONG time if you have a big project.
Give it time. Don’t panic!
Also note that I used tsconfig.json here, the one intended for the editor, not the project specific tsconfig.app.json. It’s because it might be better to upgrade any code in tests too.

The reason I used tslint directly is that the -c flag didn’t work for me on Windows, not from rxjs-5-to-6-migrate directly (it is a CLI), and not from npx ng lint.
After you finish. You can also copy the contents of node_modules/rxjs-tslint/rxjs-5-to-6-migrate.json and merge them into your project’s tslint.json file, and do the whole thing using just npx ng lint --fix.

After that, run npx ng build and see if there are any few left over errors, and correct them manually.

Then you can try removing the import in main.ts, and npx ng serve to see if everything is good, and no other library breaks.

Manual RXJS Upgrades

After the RxJS automatic upgrade, npx ng build will probably still give you RxJS related errors.

Don’t worry about cannot find module ... errors. These are fake and caused by other errors above them.

The one manual change I had to do after running the above command was to go in VS Code, and Find & Replace all ObservableOf to just of. I didn’t need to fix the import statements.

You may also get a few duplicate import errors. This is rare. In my project it was caused by some file importing delay from lodash, and using the RxJS delay operator instead. They should be few enough to be not too bad to fix manually.

If you get too many errors for too many operators, make sure you did install and import rxjs-compat BEFORE running the RxJS upgrade.

Manual Library Upgrades

Some libraries might require manual upgrade.

For example, The Telerik (now Progress) Kendo UI library can be upgraded by running:

Some libraries will be upgraded automatically for you, but have some code left behind.
You’ll just have to run ng build, and fix errors manually by checking the libraries’ docs and searching.

In my experience on a relatively big project, that wasn’t too much work.

That’s It

Hopefully no pain from libraries etc.

If you are able to get the site running in the browser, and all functionality seems to be working as before, create a pull request for your team, and apologize to them for the massive size of changes due to RxJS upgrade!

Cheers,

Share With Friends:

How did I learn that?

As a bonus for coming here, I'm giving away a free newsletter for web developers that you can sign up for from here.

It's not an anything-and-everything link list. It's thoughtfully collected picks of articles and tools, that focus on Angular 2+, ASP.NET (4.x/MVC5 and Core), and other fullstack developer goodies.

Take it for a test ride, and you may unsubscribe any time.

You might also want to support me by checking these out [Thanks]: