Creating an AngularJS Upgrade Module
NgUpgrade is a library put together by the Angular team, which we can use in our application to mix and match AngularJS and Angular components and bridge the AngularJS and Angular dependency injection systems. We can call such an application a “hybrid application”, and the code required to bootstrap it an "upgrade module".
Setting up an Upgrade Module manually involves several steps and is easy to misconfigure. Nx provides a command that does it for you.
ng generate upgrade-module legacyApp --app=myapp
This will add and set up
legacyApp, and will add all the needed dependencies to
Open the generated
legacy-app-setup.ts and you will find all the code needed to bridge the AngularJS and Angular applications.
Testing Hybrid Applications
For a lot of applications, just running one command is sufficient to convert your application into a hybrid application. That's not always the case--sometimes changes are required. To make this iterative process easier, Nx creates
hybrid.spec.ts, which you can use to make sure the upgrade module works.
upgrade-module <name> <options ...>
- name (
The name of the main AngularJS module.
- app (
The name of the application to add it to.
- angularJsImport (
Import expression of the AngularJS application (e.g., --angularJsImport=node_modules/my_app).
- angularJsCmpSelector (
The selector of an AngularJS component (e.g., --angularJsCmpSelector=myComponent).
- skipPackageJson (
Do not add @angular/upgrade to package.json (e.g., --skipPackageJson). Default is
- router (
Sets up router synchronization (e.g., --router). Default is
After Upgrade Module
Nx sets up the upgrade module for you to help you get started with your upgrade process. To learn more on how to upgrade your application, once an upgrade module is set up, check out the following resources:
Talk: Upgrading Enterprise Angular Applications
In this talk at NgConf, Victor Savkin shows how to upgrade your application gradually, component by component, module by module using NgUpgrade and the Angular Router. He discusses the common problems developers face during such migrations and the patterns that can be used to remedy them.
Embedded content: https://www.youtube.com/embed/izpqQpD8RQ0
Blog: Upgrading Angular Applications
In this blog post series Victor Savkin covers similar topics but more in depth. He dives deep into NgUpgrade, including the mental model, implementation, subtleties of the API. Then he talks about different strategies for upgrading large AngularJS applications.
- NgUpgrade in Depth
- Upgrade Shell
- Two Approaches to Upgrading Angular Applications
- Managing Routers and URL
- Using NgUpgrade like a Pro: Lazy Loading AngularJS Applications
Book: Upgrading Angular Applications
You can also get a book written by Victor Savkin on the subject here.