ngUpgrade hybrid location owner during AngularJS route migration

Direct Answer

Set Angular as the location owner when migrating routes incrementally without downtime. Route-level feature flags alone do not prevent both routers from reacting to URL changes; you must explicitly configure ownership via UpgradeModule.config({ setLocationStrategy: 'angular' }) and call setUpLocationSync(upgradeModule) once after bootstrap. Shared upgraded AngularJS services remain singletons across the router boundary, but downgraded Angular services can instantiate twice if not provided as singletons in Angular.

Why Angular Should Own Location

In hybrid mode, exactly one framework pushes history entries and responds to popstate/hashchange. The Angular router is designed to drive navigation and synchronize the AngularJS $location service through the LocationSync mechanism. When Angular owns location:

• Angular navigation commits first, then $locationChangeStart/$locationChangeSuccess fire in AngularJS as a sync callback.
• The non-owner framework (AngularJS) receives URL updates but must not initiate its own navigation.
• This avoids duplicate history entries, back‑button anomalies, and race conditions between routers.

Feature Flags Do Not Isolate Routers

Splitting routes behind feature flags (e.g., /dashboard served by AngularJS, /reports by Angular) does not guarantee single‑router handling. Both routers still listen to browser navigation events unless ownership is configured. Without setLocationStrategy: 'angular', both may push to history, causing:

• Duplicate popstate handlers
• Conflicting $routeChangeStart and Angular guard execution
• Blank pages or double navigation when html5Mode(true) and PathLocationStrategy share a mismatched <base href>

Guard AngularJS $routeChangeStart with a flag that cancels handling for URLs owned by Angular routes during cutover.

Shared Service State at Router Boundaries

Upgraded AngularJS Services (via upgradeModule.upgradeProvider())

• Remain AngularJS singletons; the AngularJS injector persists across hybrid navigation.
• State survives router‑boundary transitions (e.g., user session, cached data).
• $digest timing may delay propagation to Angular components until the next zone turn.

Downgraded Angular Services (via downgradeInjectable())

• Create a new AngularJS provider per request unless the token is provided in a shared NgModule as a singleton.
• Crossing the router boundary can instantiate a second instance if the Angular provider is not singleton‑scoped.
• Access upgraded services in Angular components via upgradeModule.injector.get(UpgradeModule).injector.get('serviceName') to avoid stale references.

Cutover Checklist

1. Configure UpgradeModule.config({ setLocationStrategy: 'angular' }) before bootstrapModuleFactory.
2. Call setUpLocationSync(upgradeModule) once after hybrid bootstrap.
3. Re‑run setUpLocationSync after any lazy‑loaded Angular module loads.
4. Guard AngularJS $routeChangeStart to preventDefault() for Angular‑owned paths.
5. Verify singleton identity: log service instance IDs on both sides of a router‑boundary navigation.
6. Ensure <base href> matches for both html5Mode(true) and PathLocationStrategy.

Verification Steps

• Enable ngUpgrade debug logs to confirm only one framework pushes history.
• Add a test route with the same path in both frameworks; navigate and verify only the owner router's guards/resolvers execute.
• Run an e2e scenario crossing the AngularJS/Angular boundary; assert no duplicate popstate handlers via window.addEventListener inspection.