10 - Migrating from Angular 17 to Angular 21: A Practical Guide

# 1. Check the current Angular version
ng version

# 2. Check Node.js version
node --version

# 3. Ensure the repository is clean
git status

# 4. Create a dedicated migration branch
git checkout -b feat/angular-21-migration

# 5. Run the current test suite for a baseline
npm test -- --watch=false

# 6. Production build for baseline verification
npm run build

# 7. Check for outdated dependencies
npm outdated

# 8. Check for vulnerabilities
npm audit
    

# Update Angular CLI and Core
ng update @angular/core@18 @angular/cli@18

# If using Angular Material
ng update @angular/material@18

# If using Angular CDK
ng update @angular/cdk@18

# Resolve any peer dependency conflicts
npm install --legacy-peer-deps
    

# Automatic control flow migration
ng generate @angular/core:control-flow

# Or, for a specific project in a workspace
ng generate @angular/core:control-flow --project=my-app

# After migration, review the changes
git diff
    

<!-- *ngIf with else -->
<div *ngIf="user; else noUser">
  Welcome, {{ user.name }}
</div>
<ng-template #noUser>
  <p>Please log in</p>
</ng-template>

<!-- *ngFor with trackBy -->
<ul>
  <li *ngFor="let item of items; trackBy: trackById">
    {{ item.name }}
  </li>
</ul>

<!-- *ngSwitch -->
<div [ngSwitch]="status">
  <p *ngSwitchCase="'active'">Active</p>
  <p *ngSwitchCase="'inactive'">Inactive</p>
  <p *ngSwitchDefault>Unknown</p>
</div>
    

<!-- @if with @else -->
@if (user) {
  <div>Welcome, {{ user.name }}</div>
} @else {
  <p>Please log in</p>
}

<!-- @for with track -->
<ul>
  @for (item of items; track item.id) {
    <li>{{ item.name }}</li>
  } @empty {
    <li>No items found</li>
  }
</ul>

<!-- @switch -->
@switch (status) {
  @case ('active') { <p>Active</p> }
  @case ('inactive') { <p>Inactive</p> }
  @default { <p>Unknown</p> }
}
    

// BEFORE (Angular 17) - classic decorators
@Component({ selector: 'app-user-card' })
export class UserCardComponent {
  @Input() name: string = '';
  @Input() age: number = 0;
  @Output() selected = new EventEmitter<string>();

  onClick(): void {
    this.selected.emit(this.name);
  }
}

// AFTER (Angular 18) - signal inputs/outputs
import { input, output } from '@angular/core';

@Component({ selector: 'app-user-card' })
export class UserCardComponent {
  name = input<string>('');
  age = input<number>(0);
  selected = output<string>();

  onClick(): void {
    this.selected.emit(this.name());
  }
}
    

# Update Angular CLI and Core
ng update @angular/core@19 @angular/cli@19

# If using Angular Material
ng update @angular/material@19

# Check and fix deprecation warnings
ng build 2>&1 | grep -i "deprecated"
    

// BEFORE (Angular 18) - explicit standalone
@Component({
  standalone: true,      // Explicitly required
  selector: 'app-header',
  imports: [RouterLink, NgOptimizedImage],
  templateUrl: './header.component.html',
})
export class HeaderComponent {}

// AFTER (Angular 19) - standalone by default
@Component({
  // standalone: true is implicit, removed by schematic
  selector: 'app-header',
  imports: [RouterLink, NgOptimizedImage],
  templateUrl: './header.component.html',
})
export class HeaderComponent {}
    

import { signal, linkedSignal, resource } from '@angular/core';

@Component({ selector: 'app-product-list' })
export class ProductListComponent {
  // linkedSignal: derived signal with override capability
  selectedCategory = signal('electronics');
  currentPage = linkedSignal(() => {
    // Reset to page 1 when category changes
    this.selectedCategory();
    return 1;
  });

  // resource API: reactive async data loading
  products = resource({
    request: () => ({
      category: this.selectedCategory(),
      page: this.currentPage()
    }),
    loader: async ({ request }) => {
      const response = await fetch(
        `/api/products?cat=${request.category}&page=${request.page}`
      );
      return response.json();
    }
  });

  changePage(page: number): void {
    this.currentPage.set(page);
  }
}
    

# Update Angular CLI and Core
ng update @angular/core@20 @angular/cli@20

# If using Angular Material
ng update @angular/material@20

# After the update, start the dev server
ng serve
    

// app.config.ts - Enable zoneless
import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideClientHydration } from '@angular/platform-browser';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    // Replaces provideZoneChangeDetection()
    provideZonelessChangeDetection(),
    provideRouter(routes),
    provideClientHydration(),
  ]
};
    

# 1. Remove zone.js from dependencies
npm uninstall zone.js

# 2. Remove the polyfill from angular.json
# Find and remove "zone.js" from the "polyfills" array

# 3. Verify there are no direct imports
grep -r "zone.js" src/
    

# Update Angular CLI and Core
ng update @angular/core@21 @angular/cli@21

# If using Angular Material
ng update @angular/material@21

# Update TypeScript to 5.9
npm install typescript@5.9 --save-dev

# Verify the build
ng build
    

// 1. Improved type narrowing in templates
// TypeScript 5.9 improves narrowing support
// in @if blocks of Angular templates

// 2. Stable import attributes
import data from './config.json' with { type: 'json' };

// 3. Compiler performance improvements
// Faster builds thanks to improved caching
// and reduced memory allocations

// 4. Improved utility types for Signals
import { Signal, WritableSignal } from '@angular/core';

// NoInfer<T> prevents unwanted inference
function createState<T>(
  initial: T,
  validator: (value: NoInfer<T>) => boolean
): WritableSignal<T> {
  const state = signal(initial);
  // ...validation logic
  return state;
}
    

#!/bin/bash
# Angular 17 -> 21 Migration Script

echo "=== STEP 1: Angular 17 -> 18 ==="
ng update @angular/core@18 @angular/cli@18
npm install
ng build
npm test -- --watch=false
git add -A && git commit -m "chore: migrate to Angular 18"

echo "=== STEP 2: Angular 18 -> 19 ==="
ng update @angular/core@19 @angular/cli@19
npm install
ng build
npm test -- --watch=false
git add -A && git commit -m "chore: migrate to Angular 19"

echo "=== STEP 3: Angular 19 -> 20 ==="
ng update @angular/core@20 @angular/cli@20
npm install
ng build
npm test -- --watch=false
git add -A && git commit -m "chore: migrate to Angular 20"

echo "=== STEP 4: Angular 20 -> 21 ==="
ng update @angular/core@21 @angular/cli@21
npm install
ng build
npm test -- --watch=false
git add -A && git commit -m "chore: migrate to Angular 21"

echo "=== Migration complete! ==="
ng version
    

# If ng update fails due to peer dependencies
# Strategy 1: Force the update
ng update @angular/core@21 @angular/cli@21 --force

# Strategy 2: Manually update conflicting dependencies
npm install @angular/core@21 @angular/cli@21 --legacy-peer-deps
npm install

# Strategy 3: Use --allow-dirty if you have uncommitted changes
ng update @angular/core@21 --allow-dirty

# Strategy 4: Clean install from scratch
rm -rf node_modules package-lock.json
npm install

# Verify dependency status
npm ls @angular/core
    

# 1. List all Angular-related dependencies
npm ls | grep angular

# 2. Check available versions
npm view @angular/material versions --json | tail -20
npm view @ngrx/store versions --json | tail -20

# 3. Update primary dependencies
ng update @angular/material@21
ng update @ngrx/store@21

# 4. For libraries without ng update schematics
npm install ngx-translate@latest
npm install primeng@latest

# 5. Verify compatibility after update
ng build
npm test -- --watch=false
    

# 1. Run all unit tests
npm test -- --watch=false --browsers=ChromeHeadless

# 2. Run e2e tests (if present)
npm run e2e

# 3. Production build (catches AOT errors)
ng build --configuration=production

# 4. Start the SSR server and verify manually
npm run serve:ssr:portfolio

# 5. Check for deprecation warnings
ng build 2>&1 | grep -i "warning\|deprecated"

# 6. Verify performance with Lighthouse
npx lighthouse http://localhost:4200 --output=json --output-path=./lighthouse-report.json
    

// BEFORE: TestBed with NgModule-style
beforeEach(async () => {
  await TestBed.configureTestingModule({
    declarations: [MyComponent],   // deprecated with standalone
    imports: [HttpClientTestingModule],
    providers: [MyService]
  }).compileComponents();
});

// AFTER: TestBed with standalone components
beforeEach(async () => {
  await TestBed.configureTestingModule({
    imports: [MyComponent],   // standalone component goes in imports
    providers: [
      provideHttpClientTesting(),  // new provider-based testing
      MyService
    ]
  }).compileComponents();
});

// BEFORE: fakeAsync with Zone.js
it('should load data', fakeAsync(() => {
  component.loadData();
  tick(1000);
  expect(component.data).toBeTruthy();
}));

// AFTER: async/await without Zone.js
it('should load data', async () => {
  component.loadData();
  await fixture.whenStable();
  fixture.detectChanges();
  expect(component.data()).toBeTruthy();  // signal()
});