The Complete Guide to Updating Your Angular Application

Gerome Grignon

Gerome Grignon

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:

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:

# 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:

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

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:

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:

# 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:

Step 2: Update One Major Version at a Time

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

# 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:

# 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:

# 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:

npm ERR! ERESOLVE unable to resolve dependency tree

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

TypeScript Version Mismatches

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

# 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:
rm -rf node_modules/.cache
rm -rf .angular/cache
  1. Reinstall dependencies:
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

# Unit tests
ng test

# E2E tests
ng e2e

2. Verify Build Succeeds

# Development build
ng serve

# Production build
ng build --configuration production

3. Manual Testing

Test critical user flows manually:

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:

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! 🚀