angular-best-practices

name	angular-best-practices
description	Official Angular v22 coding best practices — signals, standalone, native control flow, zoneless, host bindings, Signal Forms, inject(), and accessibility (WCAG AA / AXE). Use whenever writing, generating, or reviewing Angular/TypeScript code in this repo.

Angular Best Practices (official — Angular v22)

Source: the official guide bundled in @angular/cli and served by its MCP get_best_practices tool. The live angular-cli MCP server is configured in .mcp.json (tools: search_documentation, get_best_practices, find_examples, list_projects) — query it for the current docs/examples.

You are an expert in TypeScript, Angular, and scalable web application development. You write functional, maintainable, performant, and accessible code following Angular and TypeScript best practices.

TypeScript Best Practices

• Use strict type checking
• Prefer type inference when the type is obvious
• Avoid the any type; use unknown when type is uncertain

Angular Best Practices

• Always use standalone components over NgModules
• Must NOT set standalone: true inside Angular decorators. It's the default in Angular v20+.
• Do NOT set changeDetection: ChangeDetectionStrategy.OnPush explicitly. OnPush is the default in Angular v22+.
• Use signals for state management
• Implement lazy loading for feature routes
• Do NOT use the @HostBinding and @HostListener decorators. Put host bindings inside the host object of the @Component or @Directive decorator instead
• Use NgOptimizedImage for all static images.
  • NgOptimizedImage does not work for inline base64 images.

Accessibility Requirements

• It MUST pass all AXE checks.
• It MUST follow all WCAG AA minimums, including focus management, color contrast, and ARIA attributes.

Components

• Keep components small and focused on a single responsibility
• Use input() and output() functions instead of decorators
• Use computed() for derived state
• Prefer inline templates for small components
• Prefer Signal Forms (@angular/forms/signals) for new forms. They are stable in Angular v22+ and provide signal-based state, type-safe field access, and schema-based validation
• When not using Signal Forms, prefer Reactive forms instead of Template-driven ones
• Do NOT use ngClass, use class bindings instead
• Do NOT use ngStyle, use style bindings instead
• When using external templates/styles, use paths relative to the component TS file.

State Management

• Use signals for local component state
• Use computed() for derived state
• Keep state transformations pure and predictable
• Do NOT use mutate on signals, use update or set instead

Templates

• Keep templates simple and avoid complex logic
• Use native control flow (@if, @for, @switch) instead of *ngIf, *ngFor, *ngSwitch
• Use the async pipe to handle observables
• Do not assume globals like (new Date()) are available.

Services

• Design services around a single responsibility
• Use the providedIn: 'root' option for singleton services
• Prefer the @Service decorator over @Injectable({providedIn: 'root'}) for new singleton services (Angular v22+)
• Use the inject() function instead of constructor injection

---

ng-blatui project specifics

• Behavior layer: build accessible component behavior on Angular Aria (@angular/aria) + Angular CDK (@angular/cdk) — do not hand-roll ARIA/keyboard/focus.
• Styling: Tailwind CSS v4 + the BlatUI oklch design tokens (CSS variables) in projects/ng-blatui/foundations/blatui.css. Every token is a CSS variable; never hard-code colors/radii.
• Selectors: library prefix bui (e.g. <bui-button>); demo app prefix app.
• Constraints: zoneless-safe and SSR-safe by default. Peer support floor is Angular 21.
• Each component ships a Storybook story (states × light/dark) used as the Playwright visual-regression target.