angular-optimizer

---
name: angular-optimizer
description: Audit and optimize Angular apps (Angular 22.2, zoneless change detection, OnPush by default, signals/resources/Signal Forms, standalone components, Angular Material/Aria/CDK, SSR with incremental hydration, esbuild/Vite builder, Vitest) for change-detection and template cost, RxJS/subscription and memory leaks, bundle size and lazy loading, SSR/hydration and TTFB, forms and accessibility, strict typing, and major-version migrations, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching code. Use this whenever the user mentions a slow Angular app, Angular 17/18/19/20/21 to 22 upgrade, zoneless or zone.js, OnPush/Eager/ChangeDetectionStrategy, signals/computed/effect/resource/httpResource, Signal Forms, standalone/NgModules, @defer/lazy routes, Angular Material/Aria/CDK, SSR/hydration, bundle budgets, or "optimize my Angular app" -- even if they never say "audit" or "optimize".
---

# Angular Optimizer

Audit an Angular codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Angular 22 made performance defaults stricter (zoneless since v21, OnPush by default) and those defaults expose code that mutates state without notifying Angular; changing change detection, hydration or rendering mode can silently change behavior, so nothing is edited before approval.

## Workflow

### 1. Scope (quick)

- Find the workspace root (`package.json` with `@angular/core`, `angular.json`). Record: Angular version (22.2 current), Node/TypeScript/RxJS versions, standalone vs NgModule, zoneless vs `provideZoneChangeDetection`, SSR/prerender, Material/CDK/Aria, test runner (Vitest default since v21), and whether it is a multi-project workspace.
- Run `python <skill-dir>/scripts/audit.py <project-root>` -- static scan of `package.json`, `angular.json`, `tsconfig*.json`, and `.ts/.html` sources for version skew, zone.js and OnPush migration gaps, legacy control flow/NgModules, eager routes, missing budgets, SSR/hydration gaps, subscriptions/timers/DOM leaks, XSS and strict-type issues, with file:line evidence. Use `--json` to post-process.
- Classify the pain: slow initial load (bundle/SSR), slow interactions (change detection/templates), memory growth (subscriptions/listeners), hydration/SEO, forms/a11y, test/build speed, or upgrade/migration. Ask which hurts if unclear.
- Read `references/tooling.md` once: what can be measured here (`ng build`, `ng test`, stats JSON, Angular DevTools, Chrome Angular track, Lighthouse).

### 2. Audit

The script finds cheap leads; you find the rest by reading. Read `angular.json`, `tsconfig.json`, `src/main.ts`, `src/app/app.config.ts`, the 3-5 hottest routes/components and the services they call. Load only what applies:

| Area                                                          | Reference                          |
| ------------------------------------------------------------- | ---------------------------------- |
| Zoneless, OnPush/Eager, change-detection cost, templates      | `references/change-detection.md`   |
| signals, computed/effect, resource/httpResource, RxJS interop | `references/signals-state.md`      |
| SSR, prerender, hydration, incremental hydration, TTFB        | `references/ssr-hydration.md`      |
| Standalone, lazy routes, `@defer`, budgets, bundle analysis   | `references/bundle-build.md`       |
| Control flow, track, forms, validation, accessibility         | `references/templates-forms.md`    |
| Subscriptions, timers, DOM listeners, large lists, profiling  | `references/runtime-memory.md`     |
| Sanitization, XSS, secrets, auth, strict types, tests         | `references/safety-quality.md`     |
| Angular 17 → 22 migration, zoneless/OnPush/Vitest changes     | `references/migration-v22.md`      |
| Measurement and honest reporting                              | `references/tooling.md`            |

**Measure, never guess.** Build for production (`ng build --configuration production`) and serve that output, or run the SSR server, then measure. Dev mode, `ng serve`, and a single warm interaction are not evidence. Record route JS/CSS, initial bundle vs budgets, SSR TTFB/HTML, change-detection cycles in Angular DevTools, LCP/INP/CLS, memory/listener counts and hydration warnings.

Mark each finding **Confirmed** (build output, profiler, code evidence) or **Suspected** (needs measuring).

### 3. Report

Fill `assets/report-template.md`, save it as `ANGULAR_OPTIMIZATION_REPORT.md` in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

### 4. Plan -- then stop for approval

Use plan mode: `EnterPlanMode` (load with ToolSearch if deferred), write the plan, present with `ExitPlanMode`; if unavailable show it in chat and wait for an explicit "go". Structure:

1. **Quick wins** -- replace template method calls with `computed`/pure pipes, add `track` to `@for` (or `trackBy` to `*ngFor`), convert `ChangeDetectionStrategy.Eager` components that are signal-ready, add `takeUntilDestroyed`/`toSignal`, clear timers/listeners, add `type="button"`, image `alt`/`NgOptimizedImage`, lazy-load heavy routes, add budgets. Low risk.
2. **Structural** -- convert manual subscriptions to signals/async pipe, split smart/presentational components, virtualize large tables (CDK), adopt `loadComponent`/`@defer`/`injectAsync`, add SSR/prerender and hydration where it fits, consolidate Material/Aria/CDK usage, split forms into signal/reactive patterns. Name each behavior change.
3. **Heavy** -- Angular major upgrade, zone.js → zoneless, NgModule → standalone, Karma/Jest → Vitest, Material M2 → M3, design-system extraction, rendering-mode change. Separately approved.
   Each step: files touched, expected effect, how to verify, how to roll back.

### 5. Fix

Only approved items, in small groups. After each: `ng build`, `ng test`, `ng lint`, and the affected route/profile. A break must trace to one change. Do not mix a major-version migration with optimization edits. If a change alters public component inputs/outputs, routing/rendering mode, auth/data flow, or hydration boundaries, stop and ask.

### 6. Verify and wrap up

Re-measure the same routes and interactions: initial/route JS and CSS, build output vs budgets, SSR TTFB/HTML, Angular DevTools change-detection cycles, LCP/INP/CLS, memory/listener counts, hydration warnings, test time. State plainly what could not be measured. End with deferred items and one suggested next step.

## Principles

- **Angular 22 defaults are performance defaults.** New apps are zoneless (v21+) and components are OnPush by default; `ChangeDetectionStrategy.Default` is now `Eager`. Treat explicit `Eager` as migration debt.
- **Signals are the notification mechanism.** In zoneless apps, a mutation that does not touch a signal, input, bound event or `markForCheck()` may not render. Convert state, not just templates.
- **OnPush exposes hidden mutation.** Mutating arrays/objects in place, storing subscription values on plain fields, or writing from outside Angular can freeze the view. Prefer immutable updates and signals.
- **Templates are code.** Method/getter calls, pipes that allocate, and heavy expressions run per check. Move work to `computed`, pure pipes or precomputed view models.
- **Ship less by default.** `loadComponent`, `@defer`, `injectAsync`, `NgOptimizedImage`, budgets and no zone.js beat micro-optimizations.
- **Hydration is a contract.** SSR markup must match client render; direct DOM access, random/time values and invalid HTML break it. Incremental hydration is on by default with `provideClientHydration()`.
- **Forms are a choice, not a rewrite.** Signal Forms are stable in v22 for new forms; keep working reactive forms and migrate incrementally via the compat layer.
- **Accessibility comes from CDK/Aria/Material.** Use their dialogs, menus, focus traps and labels; do not rebuild behavior with clickable divs.
- **Strict types and templates catch real bugs.** `strict`, `strictTemplates`, typed forms and no `any` at boundaries are optimization work too.
- **Migrations are one major at a time.** `ng update` migrations preserve old behavior by design; remove the compatibility shims deliberately.
- **Docs move.** Check angular.dev for the installed major and read `ng version`, not memory.

• LICENSE 1 KB
• README.md 1 KB
• SKILL.md 8 KB
• assets/report-template.md 2 KB
• references/bundle-build.md 4 KB
• references/change-detection.md 5 KB
• references/migration-v22.md 5 KB
• references/runtime-memory.md 4 KB
• references/safety-quality.md 4 KB
• references/signals-state.md 4 KB
• references/ssr-hydration.md 4 KB
• references/templates-forms.md 4 KB
• references/tooling.md 3 KB
• scripts/audit.py 26 KB