@Angular20 Standalone Rules

Documentation for Developers

Angular 20 Standalone Components Rules

⚠️ CRITICAL: CommonModule is FORBIDDEN in Standalone Components

The Rule

NEVER import CommonModule in Angular 20 standalone components:

// ❌ WRONG - Will cause build errors
import { CommonModule } from '@angular/common';

@Component({
  standalone: true,
  imports: [CommonModule],  // ❌ ERROR!
})

The Correct Way

Import only the specific directives/pipes you need:

// ✅ CORRECT
import { NgClass, NgStyle, NgIf, NgFor, AsyncPipe } from '@angular/common';

@Component({
  standalone: true,
  imports: [NgClass, NgStyle, NgIf, NgFor, AsyncPipe],  // ✅ CORRECT
})

Common Directives/Pipes Reference

Structural Directives (Prefer Built-in Control Flow)

Old Syntax Import Needed Angular 20 Alternative
*ngIf NgIf @if (condition) { } ✅ PREFERRED
*ngFor NgFor @for (item of items; track item.id) { } ✅ PREFERRED
*ngSwitch NgSwitch, NgSwitchCase, NgSwitchDefault @switch (value) { @case (1) {} } ✅ PREFERRED

Attribute Directives

Syntax Import Needed
[ngClass] NgClass
[ngStyle] NgStyle

Common Pipes

Syntax Import Needed
| async AsyncPipe
| date DatePipe
| uppercase UpperCasePipe
| lowercase LowerCasePipe
| currency CurrencyPipe
| json JsonPipe

Best Practices

1. Use Built-in Control Flow (Angular 20+)

Prefer Angular's built-in control flow syntax instead of directives:

// ✅ BEST - No imports needed!
@Component({
  template: `
    @if (isVisible) {
      <div>Content</div>
    }
    
    @for (item of items; track item.id) {
      <div>{{ item.name }}</div>
    }
  `
})

2. Only Import What You Use

Don't import directives you don't need:

// ❌ BAD - Importing unused directives
imports: [NgClass, NgStyle, NgIf, NgFor, AsyncPipe]

// ✅ GOOD - Only what's used
imports: [NgClass]  // Only if you actually use [ngClass]

3. Build Libraries After Changes

When you modify library components:

# Build the library
yarn nx build library-name

# Build dependent libraries
yarn nx build dependent-library

Automated Fix Tool

We have a script to automatically fix CommonModule imports:

# Dry run (preview changes)
node tools/scripts/fix-commonmodule-imports.js libs --dry-run

# Apply fixes
node tools/scripts/fix-commonmodule-imports.js libs

# Fix specific directory
node tools/scripts/fix-commonmodule-imports.js libs/my-lib

Error Messages

"Component imports must be standalone components, directives, pipes, or must be NgModules"

Causes:

  1. Importing CommonModule in a standalone component
  2. Library not built after changes
  3. Component not properly exported from library

Solution:

  1. Remove CommonModule from imports
  2. Add specific directives/pipes needed
  3. Rebuild the library: yarn nx build library-name

Migration Checklist

See Also