---

name: angular-expert description: Enterprise Angular v21+ architecture and testing expert. Use when writing, reviewing, or designing Angular components, services, stores, or tests. Covers Zoneless change detection, Signals, SignalStore, module boundaries, testing strategy, and architectural heuristics. Triggers on Angular file creation/modification (.component.ts, .service.ts, .store.ts, .spec.ts), architectural discussions, state management, and testing decisions.

Angular Expert

Expert guidance for enterprise Angular v21+ development. Enforces architectural heuristics that prevent maintenance nightmares at scale.

Core Architectural Imperatives

These rules apply to ALL Angular code. Violations create technical debt.

1. Standalone Components Only

All components, directives, and pipes MUST be standalone. SharedModule pattern is prohibited.

Copy@Component({
  standalone: true,
  imports: [CommonModule, RouterLink], // Explicit imports
})

2. Dependency Ladder (Strict)

Dependencies flow downward ONLY: Feature → UI → Data-Access → Utility

• Feature: Smart components, routing, orchestration
• UI: Dumb/presentational components (NO service injection)
• Data-Access: Stores, facades, HTTP services, entities
• Utility: Pure functions, validators, types

3. Component-Service Firewall

Smart components NEVER inject HttpClient, Router, or raw stores directly. Inject domain-specific Facades.

Copy// ❌ VIOLATION
constructor(private http: HttpClient) {}

// ✅ COMPLIANT
constructor(private userFacade: UserFacade) {}

4. Humble Components

Extract ALL complex logic to services/facades. Components should be thin glue with minimal branching.

5. Signals for State, RxJS for Events

• Signals: Hold data, derive values, render to view (synchronous)
• RxJS: Streams of actions, HTTP requests, complex timing coordination
• Use toSignal() to convert final Observable stage for templates

6. Push State Down

CopyGlobal State  → User session, theme, language (Root store/service)
Feature State → Filters, pagination, form data (SignalStore in route)
Component State → UI toggles, ephemeral input (signal() on component)

7. Zoneless-Ready Code

Never mutate state expecting Angular to "magically" detect it. Always use Signals or AsyncPipe. No relying on Zone.js patches for setTimeout/setInterval.

Testing Philosophy: Sociable Tests

Reject the Mockist approach. Test behavior, not implementation.

The No-Mock Policy

• ✅ Provide REAL services in TestBed
• ✅ Mock ONLY at system boundaries: Network (MSW), Time, Browser APIs
• ❌ Never use jasmine.createSpyObj or vi.fn() for services
• ❌ Never spy on internal methods

Verification Pattern

Copy// ❌ MOCKIST (Banned)
expect(spy.getUsers).toHaveBeenCalled();

// ✅ SOCIABLE (Required)
expect(screen.getByText('John')).toBeVisible();

Zoneless Testing

Copyit('should work', async () => {
  await component.doSomething();
  await fixture.whenStable(); // Wait for framework tasks
  fixture.detectChanges();    // Explicit view update
  expect(...).toBe(...);
});

Use TestBed.tick() after setting signals that drive effects.

Reference Guides

Load these when working on specific concerns:

• Architecture & Boundaries: Module boundaries, Nx constraints, Hexagonal architecture, circular dependency prevention. Load when designing new features or restructuring.

• Testing Strategy: Vitest configuration, MSW setup, Harness patterns, VRT. Load when writing tests or setting up test infrastructure.

• Signal Patterns: SignalStore, Signal Forms, computed patterns, effect synchronization. Load when implementing state management or forms.

• Code Templates: Ready-to-use templates for components, stores, tests, harnesses. Load when scaffolding new files.

Any unneeded directories can be deleted. Not every skill requires all three types of resources.