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:
1 2 |
npm i -g npm |
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.
1 2 |
npm i -D @angular/cli@latest |
There’s another missing dependency which might break the upgrade, and you’ll have to install it as well.
1 2 |
npm i -D @angular-devkit/build-angular |
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:
1 2 |
npx ng update @angular/cli @angular/core --force --from 1.5.0 |
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:
1 2 |
npx ng update --all --force --from 1.5.0 |
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 similartsline.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:
1 2 |
npx -p @angular/cli@latest ng new use-same-project-name-and-options |
RxJS Automatic Upgrade
That’s another one where order of steps is important.
First, you need to install these 2 packages:
1 2 |
npm i -D rxjs-compat rxjs-tslint |
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
.
1 2 |
import 'rxjs-compat'; |
Then, automatically convert all files to the new RxJS syntax:
1 2 |
npx tslint --fix -c "./node_modules/rxjs-tslint/rxjs-5-to-6-migrate.json" -p tsconfig.json |
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:
1 2 |
npx -p npm-check-updates ncu -u -f /^@progress/ |
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,
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]: