Angular Update Best Practices: How to Manage Dependencies and Avoid Version Conflicts

When performing an angular update, always upgrade the Angular CLI first, then core framework packages together, followed by third-party libraries in dependency order, while allowing automated migration schematics to run and verifying each step to prevent peer-dependency conflicts.

Updating an Angular workspace requires more than bumping version numbers in package.json. The ng update command in the angular/angular repository resolves peer-dependency ranges, executes automated migration schematics, and rewrites code to accommodate breaking changes. Following a controlled, step-by-step dependency strategy keeps your workspace stable and eliminates the "cannot find a version that satisfies" errors common during major version upgrades.

Update the Angular CLI First

The Angular CLI contains the latest update-metadata and migration recipes required to interpret subsequent package updates correctly. Running the CLI update first guarantees that the version of ng update processing your workspace understands the migration paths for your target versions, as implemented in the CLI's update command logic.

ng update @angular/cli

After this completes, commit the changes to package.json and your lock file before proceeding.

Upgrade Core Angular Packages Together

Angular core packages—including @angular/core, @angular/common, @angular/compiler, and @angular/router—share synchronized version numbers and strict peer-dependency requirements. Updating them as a set prevents mismatched peer-dependency ranges where a library expects @angular/core ^14 while the workspace contains 15.0.0.

ng update @angular/core @angular/compiler-cli @angular/router

This ensures all framework internals remain compatible and schematics can apply transformations across the entire codebase consistently.

Resolve Peer-Dependency Warnings Manually

When ng update encounters an unsatisfiable peer-dependency constraint, it stops execution and prints a clear warning message. Do not force the installation using --force; instead, address the conflict manually by either upgrading the dependent library or maintaining the current Angular version until the library releases a compatible update, as the CLI source code indicates for conflict resolution scenarios.

Inspect the error output to identify which package requires a specific version range, then adjust your update plan accordingly.

Update Third-Party Libraries in Dependency Order

Update third-party libraries one at a time, respecting their dependency hierarchy. If a library depends on another package, update the lower-level dependency first. For example, @angular/material depends on @angular/cdk, so you must upgrade CDK before Material to avoid inter-dependency issues, according to the Angular using-libraries guide.

ng update @angular/cdk   # First, satisfies Material's peer dependency

ng update @angular/material

This sequential approach prevents situations where a library attempts to install against a peer dependency that does not yet exist in your node_modules directory.

Execute Migration Schematics After Each Update

Major Angular releases ship with update schematics that perform automated code modifications, such as renaming APIs, updating import paths, or adding required configuration to angular.json and tsconfig.json. The CLI runs these automatically when you invoke ng update for a specific package.

Review the generated diff carefully before committing. These schematics modify source files in src/**/*.ts and src/**/*.html, and may add compiler options like strictTemplates to your TypeScript configuration. Commit these changes before proceeding to the next package update.

Verify Workspace Stability Before Proceeding

After each individual update, verify that your workspace remains stable. Run your test suite or at least a production build to catch regressions early. The Angular team's recommended "Act → Wait → Assert" pattern applies here: execute the build, ensure the process finishes, and confirm the exit code indicates success.

ng build --configuration production
ng test --watch=false

This verification step prevents cascading failures where multiple breaking changes compound and become difficult to debug.

Lock Final Versions in package.json

When the update sequence completes, commit the updated package.json alongside your lock file (package-lock.json or pnpm-lock.yaml). This guarantees reproducible installs for all collaborators and CI pipelines, ensuring that node_modules remains consistent across environments.

The lock file captures the exact versions resolved during the update process, including any transitive dependency changes that ng update calculated to satisfy peer requirements.

Use the Angular Update Guide for Complex Migrations

For major version jumps spanning multiple releases, use the interactive Angular Update Guide. Access this via ng update --help to generate a customized step-by-step plan based on your current and target versions, as documented in the CLI help system.

This guide provides specific instructions for your exact version delta, including which packages require interim updates before reaching the final target version.

Summary

• Always update the CLI first to ensure compatible migration metadata and schematic execution.
• Upgrade core Angular packages as a set (@angular/core, @angular/common, @angular/compiler) to maintain synchronized peer-dependency ranges.
• Update third-party libraries sequentially in dependency order (e.g., @angular/cdk before @angular/material).
• Never use --force to bypass peer-dependency conflicts; resolve them manually by upgrading dependencies or waiting for compatible releases.
• Run and commit migrations after each package update, reviewing changes to src/**/*.ts, angular.json, and tsconfig.json.
• Verify builds and tests between steps to isolate regressions early.
• Commit lock files after completion to ensure reproducible installs across teams.

Frequently Asked Questions

What order should I follow when updating Angular packages?

Update the Angular CLI first, then core framework packages (@angular/core, @angular/common, @angular/compiler-cli) together as a single command. Afterward, update third-party libraries one at a time in dependency order, ensuring lower-level dependencies like @angular/cdk are upgraded before packages that depend on them, such as @angular/material.

Can I use --force to resolve dependency conflicts during ng update?

No, you should not use --force to bypass peer-dependency conflicts. When ng update reports a conflict, it indicates that a package in your workspace requires a different version range than what is being installed. Resolve this by upgrading the dependent library first, or postpone the Angular update until the library publishes a compatible version.

How do I handle third-party libraries that haven't released compatible versions?

If a library has not published a version compatible with your target Angular release, remain on your current Angular version until the library updates. Alternatively, check if the library has a pre-release or beta version that supports the new Angular version, and test it in a separate branch before updating your production workspace.

What files does ng update modify during the process?

ng update modifies package.json to bump version ranges, updates your lock file (package-lock.json or pnpm-lock.yaml) to lock resolved versions, and executes schematics that may alter angular.json, tsconfig.json, and source files in src/**/*.ts and src/**/*.html. Always review these changes in version control before committing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}