Hybrid application (AngularJS + Angular)

A hybrid application runs AngularJS and Angular together in the same page, usually through ngUpgrade, so that code can be migrated piece by piece.

In a hybrid application both frameworks are loaded and bootstrapped in the same browser page. They share one DOM. Angular components can appear inside AngularJS templates, AngularJS components can appear inside Angular templates, and services can be injected across the boundary. The official @angular/upgrade package, known as ngUpgrade, provides this bridge.

The purpose of the hybrid state is to keep shipping. The team migrates one component or one service at a time, and each release contains a little less AngularJS than the one before.

Example

A CRM built in AngularJS needs a new customer timeline. The team writes it as an Angular component, registers it for use in AngularJS and places it in an existing AngularJS view:

<div ng-controller="CustomerCtrl as vm">
  <h2>{{ vm.customer.name }}</h2>
  <customer-timeline [customer-id]="vm.customer.id"></customer-timeline>
</div>

The rest of the screen is unchanged AngularJS. The timeline is modern Angular.

Common misunderstanding

A hybrid application is a transition state, and treating it as a destination is costly. Users download two frameworks. Two change detection mechanisms run and have to be kept in sync, which affects performance on busy screens. Developers need to know both frameworks and the rules of the bridge. Set an end date and track how much AngularJS is left.

The hybrid route fits best when one team owns a mid-size application. For large products with several teams, splitting by route into separate applications may work better. See Rewrite, hybrid or micro-frontends for the comparison.

Related terms

• ngUpgrade (UpgradeModule)
• Downgrade (downgradeComponent / downgradeInjectable)
• Strangler fig pattern
• Change detection