angular-best-practices（Angular 最佳实践）

Modern Angular Best Practices

A comprehensive set of 112 rules covering TypeScript strictness, signal-based reactivity, component architecture, template optimization, RxJS patterns, SSR hydration, bundle optimization, accessibility, routing, forms, testing, and styling — so every component, service, template, and route you build is fast, accessible, tested, and maintainable.

Below are the key patterns organized by what you're working on. For edge cases or when you need specific code examples beyond what's listed here, consult the AGENTS.md reference file in this skill directory.

Components & Signals

Components are the building blocks. Modern Angular uses signals for reactivity, which changes how you write everything from state to templates.

• Use standalone components with ChangeDetectionStrategy.OnPush
• Use input(), output(), model() signal functions instead of decorators
• Use inject() instead of constructor injection
• Use signal() for local state, computed() for derived state
• Use linkedSignal() when state should reset when a source changes
• Use resource() / httpResource() for async data with built-in loading states
• Use effect() only for side effects — never for state synchronization
• Use toSignal() to bridge RxJS observables into signal-based templates
• Use viewChild() / contentChild() signal queries instead of decorators
• Use the host property instead of @HostBinding / @HostListener

Templates & Styles

Templates and styles work together — accessibility, layout, and performance cross both concerns.

• Use @if, @for, @switch control flow instead of structural directives
• Use @defer for heavy below-fold content
• Always provide track with @for loops
• Use NgOptimizedImage with priority for above-fold images
• Use pure pipes instead of method calls in templates
• Use CdkVirtualScrollViewport for large lists
• Use [class.active] bindings instead of [ngClass]
• Define theme values as CSS custom properties
• Use prefers-reduced-motion to respect motion preferences

Services & RxJS

Services handle data flow, dependency injection, and RxJS patterns. HTTP, caching, and observable lifecycle are interconnected concerns.

• Unsubscribe via takeUntilDestroyed() or async pipe
• Place catchError inside switchMap to keep the outer stream alive
• Use switchMap for latest-only, exhaustMap for ignore-while-busy
• Use shareReplay({bufferSize: 1, refCount: true}) for shared streams
• Use inject() with InjectionToken for configuration
• Use HTTP interceptors for cross-cutting concerns (auth, retry, logging)
• Map DTOs at the API boundary — don't leak backend shapes into components

Performance & SSR

Performance rules span components, templates, and infrastructure. SSR affects routing, data fetching, and hydration strategy.

• Preload critical data with route resolvers to eliminate waterfalls
• Lazy-load routes and @defer heavy views
• Tree-shake imports via standalone component imports, not modules
• Batch DOM reads/writes to avoid layout thrashing
• Use Map/Set over plain objects/arrays for frequent lookups
• Use incremental hydration (@defer (hydrate on...)) for large pages
• Use provideClientHydration(withEventReplay()) for SSR
• Set render modes per-route: SSR for SEO, CSR for dashboards

Testing

Testing patterns apply to components, services, and templates together — isolation is important but integration context matters.

• Use component harnesses over direct DOM queries
• Create test object factories for consistent test data
• Test signal state changes and template output, not implementation
• Mock services with jasmine.createSpyObj or jest.fn()
• Test accessibility with axe-core or jest-axe

Architecture & Routing

Architecture decisions affect every file type — routing, module boundaries, and dependency injection are structural.

• One feature per lazy-loaded route
• Use guards for auth, resolvers for data, canDeactivate for unsaved changes
• Use preload strategies (QuickLinkStrategy) for likely-next routes
• Bind route params via input() with withComponentInputBinding()
• Avoid barrel file re-exports — import directly from source
• Use environment-based configuration — no hardcoded URLs or API keys

TypeScript Foundations

These apply everywhere — components, services, tests, all .ts files.

• Use strict type checking with strict: true in tsconfig
• Avoid any; use unknown when type is uncertain, generics to narrow
• Use import type for type-only imports
• Add explicit return types to exported functions
• Prefer readonly for data that should not be mutated
• Use discriminated unions for state variants
• Use the Result pattern for operations that can fail

Accessibility

Accessibility spans templates, styles, and components — it's not just an HTML concern.

• Use semantic HTML elements first (<nav>, <main>, <button>)
• Use ARIA roles and aria-live regions for dynamic content
• Ensure all interactive elements are keyboard-accessible
• Use cdkTrapFocus for dialogs and overlays
• Test with screen readers and axe-core

Quick Reference

Key Code Patterns

Signal inputs and outputs (replaces decorators):

name = input<string>();           // @Input() replacement
save = output<Data>();            // @Output() replacement
value = model<string>();          // two-way binding

Control flow (replaces structural directives):

@if (user()) { <profile [user]="user()" /> }
@for (item of items(); track item.id) { <card [item]="item" /> }
@defer (on viewport) { <heavy-chart /> }

httpResource and resource (signal-based async):

users = httpResource<User[]>(() => `/api/users?role=${this.role()}`);
data = resource({ request: () => this.id(), loader: ({request}) => fetch(request) });

Optional Library Skills

Install library-specific rules alongside this core skill:

Links

• GitHub Repository
• Submit a Rule via GitHub Issues
• Browse All Skills

License

MIT