Web & Mobile Development
Migrating from AngularJS to Angular: Strategies, Sequencing and Risk
Advanced10 min readUpdated
AngularJS reached end of life in 2021, so every remaining application is running unpatched on a framework nobody maintains. This guide compares the architectures honestly, shows how to prepare a legacy codebase so that any migration route becomes cheaper, weighs hybrid bootstrapping against side-by-side delivery and a rewrite, and maps each AngularJS concept onto its modern replacement.
What you will learn
- Justify a migration in terms of risk, cost and maintainability rather than fashion
- Explain the architectural differences between scopes with a digest loop and components with signals
- Prepare an AngularJS codebase so that the eventual migration is smaller and safer
- Choose between hybrid bootstrapping, side-by-side delivery and a rewrite for your situation
- Translate controllers, directives, filters, services and routes to their modern equivalents
- Keep the application releasable and tested throughout a multi-month transition
Every AngularJS application still in production is running on a framework that stopped receiving patches on the last day of 2021. Nothing dramatic happened on that date — the code kept working — but the risk profile changed permanently. There will be no fix for the next vulnerability found in the framework or in the long tail of abandoned directives most of these applications depend on, browsers keep evolving underneath, and the pool of developers willing to work on it shrinks every year.
That is the argument for migrating, and it is a risk argument rather than an aesthetic one. It matters because migrations are approved by people who need a reason beyond "the new one is nicer". What follows is the practical side: how the two architectures actually differ, what to do to the legacy codebase before you start, how to choose a delivery strategy, and how to keep shipping features while the transition runs.
Two frameworks with the same name and different foundations
The naming is unfortunate — AngularJS and Angular share a brand and very little else. Understanding where the models diverge tells you which parts of a port are mechanical and which require rethinking.
| Concern | AngularJS | Angular |
|---|---|---|
| Unit of UI | Controller plus template, later .component() | Class with a decorator, standalone by default |
| State container | $scope, with prototypal inheritance | Class fields, usually signals |
| Update mechanism | Digest loop re-evaluating every watcher until stable | Targeted change detection driven by inputs, events and signals |
| Data flow | Two-way binding almost everywhere | One-way down, events up |
| Dependency injection | By string name, with annotation needed for minification | By type or token, resolved through a hierarchical injector |
| Language | ES5 JavaScript, later ES6 | TypeScript, strongly typed templates |
| Modularity | angular.module registries and a global namespace | ES modules and the compiler's import graph |
| Composition unit | Directives with a link function | Components and attribute directives |
| Tooling | Concatenation, Grunt or Gulp | CLI, ahead-of-time compilation, tree shaking |
The digest loop is the piece that most shapes a legacy codebase. Because AngularJS could not know what changed, it re-evaluated every registered watcher repeatedly until values stabilised, capped at ten passes. That produced the familiar performance cliff past a few thousand bindings, the $apply already in progress errors when code ran outside the framework's knowledge, and the habit of adding $scope.$watch to glue things together. Modern Angular inverts this: it knows precisely which bindings depend on which state, so an update touches only the affected components. Any logic in your application that exists to compensate for the digest loop can simply be deleted, but you have to recognise it first.
The second structural difference is scope inheritance. A child scope inherited from its parent, so a template could read a value defined three levels up and — thanks to JavaScript prototypes — writing a primitive on the child silently shadowed the parent instead of updating it. This produced a whole genre of bug and a folk rule ("always have a dot in your ng-model"). There is no equivalent in the new model: data arrives through explicit inputs, and nothing is implicitly visible from an ancestor.
Assess before you plan
Start with an inventory, not a proof of concept. Count the screens and route definitions. List every third-party directive, module and jQuery plugin, and mark which are abandoned. Measure how much logic lives in controllers versus services — logic already in services is largely portable, logic in controllers usually is not. Find the shared state: authentication, the current user, permissions, a cart, an in-memory cache. Shared state is what determines whether the old and new applications can run side by side or must be interleaved.
Then be honest about the destination. A migration is a rare opportunity to fix an architecture, and equally a rare opportunity to derail a project by trying to fix everything at once. Decide explicitly what is in scope: framework only, or framework plus design system, or framework plus a new backend contract. Each addition multiplies risk. Most successful migrations keep the visual design and the API contract fixed so that behavioural differences are unambiguous defects.
Preparing the legacy codebase
Every hour spent here shrinks the conversion that follows, and none of it is wasted even if the migration is postponed.
Move from controllers to components. AngularJS 1.5 added .component(), which is deliberately close to the modern model: an isolated scope, one-way input bindings with <, output callbacks with &, and a controller class with controllerAs instead of $scope. Converting a screen to this shape is the single highest-value preparation step, because the resulting component maps almost line for line onto its replacement.
angular.module('orders').component('orderRow', {
bindings: { order: '<', onRemove: '&' }, // one-way in, callback out
controllerAs: 'vm',
template: `
<tr>
<td>{{ vm.order.reference }}</td>
<td><button ng-click="vm.onRemove({ id: vm.order.id })">Remove</button></td>
</tr>`,
controller: function () { /* no $scope */ },
});
Eliminate $scope dependence. Replace $scope.$watch with explicit method calls, $scope.$emit and $scope.$broadcast with a service holding the state, and any reliance on scope inheritance with an explicit binding. Event buses across scopes are the hardest thing to port because the dependencies are invisible.
Adopt ES modules and a build. Replace globals and concatenation order with import/export, so the dependency graph becomes explicit and tooling can analyse it. This is also the point at which introducing TypeScript to the old codebase becomes possible, file by file, with allowJs enabled — types written now survive the migration.
Standardise structure. One component, service or filter per file; folders by feature rather than by type; consistent naming; explicit DI annotation everywhere so nothing depends on parameter names surviving minification.
Remove jQuery and abandoned plugins. Two DOM-owning systems in one page is a recurring source of migration pain, because a framework re-render silently discards changes another library made. The staged approach in the jQuery guide applies directly.
Add characterisation tests. You cannot verify a port against a specification nobody wrote. End-to-end tests over the critical journeys, written against the current application before you touch it, are what turn "it looks the same" into evidence. Run them on every commit in the pipeline described in continuous integration, and see test automation strategy for keeping that suite affordable.
Choosing a delivery strategy
Hybrid bootstrapping
The @angular/upgrade package boots both frameworks in one page. UpgradeModule starts AngularJS from within an Angular application; downgradeComponent wraps a modern component so an old template can use it; downgradeInjectable and UpgradeModule.$injector.get let services cross in both directions. You migrate leaf components first, then their parents, then routing.
The appeal is that a single screen can contain both, so there is no hard boundary and no duplicated session handling. The costs are real. Both frameworks ship in the bundle, so the application gets larger before it gets smaller. Two change-detection systems interact, and the seams — an old digest triggered by a new event, or the reverse — produce timing bugs that are hard to diagnose. Routing must be owned by one side, which usually means an awkward interim. And critically, the upgrade package has received no meaningful investment for years and is tied to the older parts of the framework, so you must confirm it works with the Angular version you intend to target before you build a plan around it. Where it fits best is a large application with deep interleaving and heavy shared state, migrated by a team that can afford to live in the hybrid state for months.
Side-by-side delivery
Here the two applications remain entirely separate and a reverse proxy or edge router decides which one serves each path — /orders to the new application, everything else to the old. There is no framework interop at all, which removes the entire class of hybrid bugs. Each application is built, tested and deployed independently, and the old bundle disappears the day the last route moves.
The costs move elsewhere. Session and authentication state must be shared, which in practice means a cookie or token both applications understand and a single sign-on flow that survives the hop. A navigation between the two is a full page load, so shared chrome must be duplicated or extracted, and there is a visible transition unless the design absorbs it. Some duplicated code is unavoidable during the overlap. For applications whose screens are genuinely independent — most back-office and administrative systems — this is usually the lower-risk route, and it is the same reasoning that leads teams to micro-frontend architectures generally.
The rewrite
Occasionally the right answer is to start again: when the application is small, when the requirements have changed so much that porting the current behaviour is pointless, or when the codebase has no tests, no structure and no one who understands it. The rewrite is the only strategy with no interop cost and the only one that carries the classic risk of a long branch that never lands while the original keeps changing. If you choose it, timebox it, freeze features on the original, and be prepared to abandon the attempt rather than let it run indefinitely.
Translating the pieces
Once a strategy is chosen, most of the work is mechanical. This mapping covers the majority of what you will meet:
| AngularJS | Modern Angular |
|---|---|
.controller with $scope | Component class with fields and signals |
.component with bindings | Component with input() and output() |
.directive with a link function | Component, or an attribute directive with host bindings |
.factory / .service / .provider | @Injectable class, provided in root or a route |
.filter | Pipe |
$http | HttpClient |
$q | Native promises, or RxJS observables |
$timeout / $interval | setTimeout / setInterval, no digest wrapper needed |
$scope.$watch | computed, effect, or an input setter |
ng-repeat | @for with a mandatory track expression |
ng-if / ng-show | @if, or a class or style binding |
ng-model on a form | Reactive forms with typed controls |
$routeProvider or ui-router states | Routes array with lazy loadComponent |
angular.module registry | ES module imports plus the component imports array |
$rootScope.$broadcast | A service holding a signal or a subject |
Two translations deserve care rather than mechanical substitution. Directives with link functions that manipulate the DOM directly are often better rewritten as components with declarative templates than transcribed literally. And anything that relied on two-way binding across several levels has to be restructured into unidirectional flow, which usually means lifting the state into a service. The target-side details of all of this are covered in Angular fundamentals.
Testing and sequencing the work
Treat the migration as a sequence of releasable increments, never as a branch. Convert one screen, get it through review, put it in production behind a flag if necessary, and only then start the next. A migration branch that runs for three months accumulates conflicts with ordinary feature work until merging it becomes its own project.
Testing operates at three levels during the transition. End-to-end tests written before the work started run against both versions unchanged — they are the contract. Unit tests generally do not port: the AngularJS ones depend on angular.mock and the injector, so plan to rewrite rather than translate them, and write the new ones as you convert each screen. In a hybrid setup, add a small number of integration tests specifically over the seams, because that is where the framework interaction bugs live.
Sequence by risk and by dependency. Start with a leaf screen that is genuinely representative — not the simplest one, which teaches you nothing about the real cost. Do shared services early, because everything depends on them, and authentication early too, since it is the hardest thing to run in two places. Leave the highest-traffic and most business-critical screens until the team has done several conversions. Keep a visible burndown of screens remaining; migrations lose funding when progress is invisible.
The recurring failure modes are worth naming. Redesigning while porting, so that every difference triggers a debate about intended behaviour. Migrating without tests and discovering regressions in production. Letting the hybrid state become permanent, which leaves you maintaining two frameworks forever. Underestimating third-party widgets — a grid or scheduler plugin with no modern equivalent can be the largest single item in the plan. And treating the migration as a background task with no owner, which is how a two-quarter project becomes a three-year one.
Key takeaways
- AngularJS has been unsupported since the end of 2021; the case for migrating is unpatched risk and vanishing expertise, not framework fashion.
- The frameworks differ at the foundation — digest loop versus targeted change detection, scope inheritance versus explicit inputs, string DI versus typed tokens — so parts of a port are rethinking rather than transcription.
- Preparing the legacy code by converting controllers to components with one-way bindings, adopting ES modules and removing jQuery makes every later step smaller and is valuable on its own.
- Hybrid bootstrapping suits deeply interleaved applications but ships two frameworks and two change-detection systems; side-by-side delivery suits clean screen boundaries and eliminates interop bugs at the cost of shared session handling.
- Most of the translation is a lookup table, but DOM-manipulating directives and multi-level two-way binding need redesign into unidirectional flow.
- Ship in releasable increments with end-to-end tests written beforehand as the contract, sequence shared services and authentication early, and keep progress visible so the work stays funded.
Sources and further reading
Frequently asked questions
- Is AngularJS really unsafe to keep running?
- Support ended on 31 December 2021, so no security patches have been issued since. The risk is not that the framework spontaneously breaks; it is that a vulnerability disclosed in it, in a bundled dependency or in an abandoned third-party directive will never be fixed. Compensating controls such as a strict content security policy and rigorous server-side validation reduce exposure, but they do not remove it.
- Should we use ngUpgrade or run the two applications side by side?
- ngUpgrade suits an application with deep interleaving, where a single screen mixes old and new components and shares services between them. Side-by-side delivery, routing whole screens to one application or the other at the edge, suits an application with clean screen boundaries and avoids shipping two frameworks in one bundle. Check the compatibility of the upgrade package with your target Angular version before committing.
- How long does a migration take?
- It scales with the number of screens and the amount of shared state rather than with lines of code. A useful estimate is to convert two representative screens end to end, measure the elapsed time honestly including review and testing, then multiply by the remaining count and add a substantial allowance for shared services, authentication and third-party widgets. Anything under a few months for a large application is usually optimism.
- Can we skip the preparation work and start converting immediately?
- You can, and on a small application that is reasonable. On a large one, preparation pays for itself: converting controllers to components with one-way bindings, moving to ES modules and adding characterisation tests all reduce the size of each later conversion and are useful even if the migration is paused. Untangling scope inheritance during the port is far more expensive than doing it beforehand.