Complete Guide to Upgrading Angular CLI: From Legacy to Latest Version

Global Angular CLI Upgrade Steps

When checking the Angular CLI version with ng --version, if an old version (e.g., 1.0.0) is displayed, an upgrade is necessary. Due to caching or permission issues, a simple update command may not work for globally installed packages. A reinstallation strategy is recommended.

First, uninstall the old globally installed CLI:

npm uninstall -g @angular/cli

Then, install the latest version:

npm install -g @angular/cli@latest

On Linux or macOS systems, if permission errors occur, prefix the commands with sudo:

sudo npm uninstall -g @angular/cli
sudo npm install -g @angular/cli@latest

After completing these steps, run ng --version again to verify the version update.

Local Project Upgrade Strategy

After upgrading the global CLI, the local project may still use an old version because node_modules in the project directory takes precedence. To ensure consistency, update local dependencies.

Navigate to the project root directory and execute the following commands:

rm -rf node_modules
npm uninstall --save-dev @angular/cli
npm install --save-dev @angular/cli@latest
npm install

The first command removes the node_modules directory to clear old dependencies; the second uninstalls the local CLI dependency; the third installs the latest CLI version as a dev dependency; and the final command reinstalls all project dependencies.

Migration from Angular CLI 1.x to 6+

When upgrading from Angular CLI 1.x to 6+, the configuration file structure changes, requiring conversion from angular-cli.json to angular.json. Use the ng update command to automate this process.

For example, migrating from version 1.7.4:

ng update @angular/cli --from=1.7.4 --migrate-only

This command updates the configuration file and adjusts the project structure to ensure compatibility with the new CLI version. After migration, check if angular.json is generated and validate the project configuration.

Post-Upgrade Angular Version Update

After CLI upgrade, it is advisable to update Angular core packages to compatible versions. Refer to the Angular Update Guide for detailed upgrade paths. Use the following command to update core packages:

ng update @angular/core @angular/cli

This command automatically adjusts version numbers in package.json and installs corresponding dependencies. If errors occur, try updating CLI or core packages separately, for example:

ng update @angular/cli
ng update @angular/core

Common Issues and Solutions

Issue 1: Build failures after upgrade. Possible causes include dependency conflicts or caching issues. Solution: Clear npm cache and reinstall dependencies:

npm cache clean --force
rm -rf node_modules
npm install

Issue 2: Version mismatches. Ensure Node.js version is compatible with Angular CLI. Refer to the official compatibility table and use nvm to switch Node.js versions:

nvm install 18  # Install Node.js 18
nvm use 18      # Switch to version 18

Issue 3: Permission errors. On non-admin accounts, global package installation may fail. Solutions: Use sudo or configure npm global installation path to the user directory.

Code Example: Verifying Upgrade Results

After upgrade, create a new project to test CLI functionality:

ng new demo-project
cd demo-project
ng serve

If the project starts successfully without errors, the upgrade is successful. Check package.json to confirm CLI and core package versions:

{
  "devDependencies": {
    "@angular/cli": "^19.0.0"
  },
  "dependencies": {
    "@angular/core": "^19.0.0"
  }
}

By following these steps, developers can systematically upgrade Angular CLI, avoid common pitfalls, and maintain a stable development environment.