angular.courses

Article

The Complete Guide to Updating Your Angular Application

GGGerome Grignon
AngularUpdateMigration

Keeping your Angular application up-to-date is crucial for security, performance, and access to the latest features. However, the update process can feel daunting, especially when jumping multiple major versions. This guide will walk you through everything you need to know to update your Angular application safely and efficiently.

Why Update?

Before diving into the how, let's understand the why:

  • Security: Newer versions include security patches and vulnerability fixes
  • Performance: Each Angular version brings performance improvements
  • Features: Access to new APIs, syntax improvements, and developer experience enhancements
  • Long-term Support: Older versions eventually reach end-of-life
  • Ecosystem Compatibility: Third-party libraries often require newer Angular versions

Pre-Update Preparation

The key to a successful update is thorough preparation. Here's what you need to do before running any update commands.

1. Audit Your Current State

Start by understanding your current Angular version and the dependencies you're using:

Terminal window
# Check your current Angular version
ng version


# Review all installed dependencies
cat package.json

2. Check Library Compatibility

One of the biggest challenges when updating Angular is ensuring your third-party libraries are compatible with your target version.

Use the Library Health Check Explorer to check if your libraries support your target Angular version. This tool shows you:

  • Which libraries are compatible with which Angular versions
  • Health scores for each library
  • Recommended versions for your target Angular version

Use the Package.json Analyzer to get personalized recommendations. Simply upload your package.json and receive:

  • Dependency compatibility analysis
  • Recommended versions for your current and target Angular versions
  • Warnings about potential conflicts

3. Review Breaking Changes

Every major Angular version comes with breaking changes. Before updating, review what changes will affect your codebase.

Use Release Insights to explore:

  • Features: New and changed features per version
  • Migrations: Available automatic migration scripts
  • Libraries: Library compatibility for each version
  • Changelogs: Detailed changelog entries

Check Can I Use - Features to see which features are available in your target version, their stability status (experimental, preview, stable, deprecated), and when they were introduced.

4. Create a Backup

Always protect yourself before making significant changes:

Terminal window
# Commit all current changes
git add .
git commit -m "chore: pre-update snapshot"


# Create a branch for the update
git checkout -b update/angular-vXX

The Update Process

Step 1: Use the Official Angular Update Guide

The Angular team provides an official update guide at update.angular.dev. This tool generates customized instructions based on:

  • Your current version
  • Your target version
  • Your application complexity

Step 2: Update One Major Version at a Time

Angular recommends updating one major version at a time. This approach:

  • Ensures all migrations run properly
  • Makes it easier to identify issues
  • Follows the tested upgrade path
Terminal window
# Update to the next major version
ng update @angular/core@XX @angular/cli@XX


# After each major version update:
# 1. Run the app
# 2. Run tests
# 3. Fix any issues
# Then proceed to the next version

Step 3: Run Angular Migrations

Angular provides automatic migration scripts that update your code for breaking changes. These run automatically during ng update, but you can also run them manually:

Terminal window
# List available migrations
ng update @angular/core --migrate-only


# Run a specific migration
ng update @angular/core --migrate-only --name=migration-name

Browse available migrations in Can I Use - Migrations to see all migration scripts, their descriptions, and which versions they're available in.

Step 4: Update Third-Party Dependencies

After updating Angular core, update your third-party dependencies:

Terminal window
# Update Angular-related packages
ng update @angular/material
ng update @angular-eslint/schematics


# Update other dependencies
npm update
# or
pnpm update

Handling Common Issues

Peer Dependency Conflicts

Peer dependency conflicts are one of the most common issues during updates. If you encounter errors like:

Terminal window
npm ERR! ERESOLVE unable to resolve dependency tree

We have a detailed guide on Resolving Peer Dependency Conflicts that covers:

  • Why conflicts happen
  • How npm, yarn, and pnpm handle them differently
  • Multiple solutions including --legacy-peer-deps and overrides

TypeScript Version Mismatches

Angular requires specific TypeScript versions. Check the Angular CLI compatibility page for the correct TypeScript version.

Terminal window
# Update TypeScript to the required version
npm install typescript@X.X --save-dev

Build Errors After Update

If you encounter build errors:

  1. Clear the cache:
Terminal window
rm -rf node_modules/.cache
rm -rf .angular/cache
  1. Reinstall dependencies:
Terminal window
rm -rf node_modules
rm package-lock.json  # or pnpm-lock.yaml
npm install  # or pnpm install
  1. Check for deprecated APIs: The Angular compiler will warn you about deprecated APIs. Address these warnings to prevent future breaking changes.

Post-Update Verification

After completing the update:

1. Run Your Test Suite

Terminal window
# Unit tests
ng test


# E2E tests
ng e2e

2. Verify Build Succeeds

Terminal window
# Development build
ng serve


# Production build
ng build --configuration production

3. Manual Testing

Test critical user flows manually:

  • Authentication flows
  • Core business functionality
  • Third-party integrations

4. Check for Deprecation Warnings

Review build output for deprecation warnings. While deprecated features still work, they'll be removed in future versions.

Advanced Tools and Resources

Track New Angular Features

Stay informed about what's new and what's changing:

Check ESLint Rule Compatibility

If you're using Angular ESLint, check which rules are available for your Angular version:

Can I Use - ESLint shows rule availability and configuration options across Angular versions.

MCP Server Features

Starting from Angular 20, the Angular CLI includes an MCP server for enhanced AI-assisted development. Check which MCP features are available in your version at Can I Use - MCP.

Want to use MCP features before v20? Check our guide on using the Angular MCP server before v20.

Update Checklist

Use this checklist for your next Angular update:

  • [ ] Check current Angular version (ng version)
  • [ ] Identify target version
  • [ ] Review Release Insights for the target version
  • [ ] Check library compatibility with Library Health Check
  • [ ] Upload package.json to Package Analyzer
  • [ ] Create a git branch for the update
  • [ ] Read the official update guide at update.angular.io
  • [ ] Update one major version at a time
  • [ ] Run ng update @angular/core @angular/cli
  • [ ] Update third-party dependencies
  • [ ] Fix any peer dependency conflicts
  • [ ] Run tests
  • [ ] Verify production build
  • [ ] Test critical functionality manually
  • [ ] Address deprecation warnings
  • [ ] Merge and deploy!

Conclusion

Updating Angular doesn't have to be stressful. With proper preparation, the right tools, and a methodical approach, you can keep your application current and take advantage of Angular's latest features.

Remember:

  1. Prepare thoroughly: Check compatibility before you start
  2. Update incrementally: One major version at a time
  3. Verify at each step: Run tests after each update
  4. Use available tools: Let automation handle what it can

The tools available on this site are designed to make your update journey smoother. Use them to plan your update, check compatibility, and understand what's changing in each version.

Happy updating! 🚀