How to upgrade Angular versions safely
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
Upgrading Angular versions is a critical task for maintaining the security, performance, and long-term stability of your enterprise applications.
With over 25 years of experience in software development and as the creator of CoreUI, I have overseen thousands of migrations for both open-source libraries and complex commercial dashboards.
The most efficient and modern solution is to use the Angular CLI’s built-in ng update command, which automates the migration of your code and dependencies.
This process ensures that your application remains robust while leveraging the latest features of the framework.
Use the Angular CLI ng update command to systematically transition between major versions and apply automated code migrations.
# Check for available updates
ng update
# Update Angular CLI and Core to the next major version
ng update @angular/core @angular/cli
The first command, ng update, analyzes your package.json and identifies which dependencies have newer versions compatible with the Angular update lifecycle. The second command actually performs the update, downloading the new packages and running “schematics”—scripts that automatically rewrite parts of your source code to comply with new APIs or deprecations. This ensures that you don’t just update the version number, but also maintain a functional codebase.
1. Ensure a Clean Working State
Before you start any upgrade process, it is essential to have a clean git repository. This allows you to revert changes immediately if a migration script behaves unexpectedly or if the build fails after the update.
# Check if there are any uncommitted changes
git status
# If changes exist, commit them or stash them
git add .
git commit -m 'chore: prepare for angular upgrade'
Working from a clean slate is a non-negotiable step in professional development. It provides a safety net that lets you experiment with the upgrade without the risk of losing existing work. We follow this exact protocol when preparing our Angular Dashboard Template for new framework releases. Ensuring that your unit tests pass before you start is also highly recommended to establish a reliable baseline for the migration.
2. Identify the Upgrade Path
Angular supports upgrading one major version at a time. If you are on version 15 and want to move to version 17, you must first upgrade to version 16. Skipping versions is not supported and often leads to broken dependencies.
# Verify your current version
ng version
# Visit the official guide: update.angular.io
# Select your current version and target version to see specific instructions
The official Angular Update Guide is your best friend during this process. It provides a checklist of breaking changes and specific steps required for your unique configuration. By following the incremental path, you ensure that the schematics for each version have the opportunity to transform your code correctly. This systematic approach is how we keep the Free Angular Admin Template up to date with zero downtime for developers.
Before upgrading, also verify your Node.js version. Each major Angular release requires a minimum Node.js LTS version — for example, Angular 18 requires Node.js 18.19 or later. Run node -v and cross-reference it with the Angular compatibility table before proceeding.
3. Update the CLI and Core Packages
The core of the upgrade process involves updating the @angular/cli and @angular/core packages. These two are tightly coupled and should almost always be updated together to ensure compatibility between the build tools and the framework logic.
# Run the update for core and cli
ng update @angular/core @angular/cli
# Use the --force flag only if you have peer dependency conflicts you can't resolve
# ng update @angular/core @angular/cli --force
When you run this command, the Angular CLI doesn’t just change the numbers in your package.json. It executes complex logic that looks for deprecated patterns in your components and replaces them with modern equivalents. For example, it might update your inject syntax or adjust how ViewChild is used. If you encounter errors about peer dependencies, try to update those specific libraries first before resorting to the --force flag.
4. Migrating Third-Party Dependencies
Once the core framework is updated, you must address third-party libraries like RxJS, TypeScript, and UI kits. Many of these libraries provide their own schematics that can be triggered via the CLI.
# Example: Updating RxJS if requested by the CLI
ng update rxjs
# Update other libraries that support ng update
ng update @angular-eslint/schematics
Maintaining compatibility with the ecosystem is just as important as the framework itself. If a library doesn’t support ng update, you will need to manually update it via npm install and check its migration guide for breaking changes. In our CoreUI components, we ensure that our Angular documentation reflects the latest requirements so that our users have a seamless experience when they decide to move forward.
5. Verify the Build and Run Tests
The final step is to verify that the automated migrations worked as expected. This involves running the development server, building the production bundle, and executing your test suite.
# Run unit tests to catch regressions
ng test
# Run the development server
ng serve
# Perform a production build to check for AOT compilation errors
ng build --configuration production
Automated migrations are powerful but not infallible. You should manually inspect areas of your code that was modified by the CLI. Common issues include CSS selector changes or subtle shifts in lifecycle hook timing. Verify that all your components still render correctly after the upgrade. Validation is the only way to guarantee that your “safe” upgrade is truly successful.
6. Cleanup and Optimization
After a successful upgrade, it is common to find leftover configuration files or deprecated properties in your angular.json. Use this opportunity to clean up your workspace and adopt new features.
# Remove node_modules and package-lock.json if you encounter weird caching issues
rm -rf node_modules package-lock.json
npm install
# Check for new recommended flags in angular.json
# Often, new versions introduce better build optimizations
Modernizing your configuration can lead to significantly faster build times and smaller bundle sizes. We always recommend checking if you can improve your logic, such as switching to more efficient ways to use ngfor in angular if the new version offers better performance. Once everything is verified, commit your changes with a clear message indicating the new version number.
Best Practice Note:
Always perform major upgrades in a dedicated branch and never directly on your main production line.
For large enterprise apps, we recommend an “audit phase” where you review the migration logs produced by the CLI. This is the same rigorous approach we take at CoreUI to ensure that every release of our templates is rock-solid. Remember to also update your Node.js version if the new Angular release requires it — skipping this step is one of the most common causes of mysterious build failures after an upgrade.
