Diagnose and fix Angular runtime and load performance — change detection doing too much work, template work on every check, oversized bundles, slow LCP and high INP, janky lists and tables, memory growth from undisposed subscriptions.
When agents use itUse this whenever the user says an Angular app is slow, laggy or stutters, reports high TTFB/LCP/INP/CLS or a failing Lighthouse score, sees long tasks or a growing heap, has a table or list that drags while scrolling or typing, hits a bundle-budget error in `ng build`, or asks how to profile with Angular DevTools, `--stats-json`, `@defer`, `track`, virtual scroll or `NgOptimizedImage`. Also use it when a "slow API" turns out to be a client-side waterfall; for SSR, hydration and TransferCache use angular-ssr.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill angular-performance -a github-copilot
# or with the org installer (adds .github/skills/angular-performance):
npx -y github:AGCO-Global/org-skills add skill angular-performance
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the frontend-angular-skills plugin, which bundles all Frontend / Angular skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-angular-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill angular-performance -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill angular-performance -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill angular-performance -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill angular-performance -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the angular-performance folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Every Angular performance complaint belongs to one of four buckets: change detection running too often, templates doing work on every check, too much JavaScript shipped, or the network (waterfalls, refetches, unbounded data). Measure first, name the bucket, then fix. A fix applied to the wrong bucket costs a sprint and changes nothing.
1. Decide first
Question
Default
Change when
Where to start
Reproduce on a production build (ng build then serve the output) and record a baseline number
Never skip. Dev-mode numbers include double change detection and unminified code
Which bucket
Angular DevTools Profiler if interaction is slow; Lighthouse + bundle analysis if first load is slow
A growing heap across navigations → DevTools heap snapshots instead
Change-detection strategy
OnPush (the framework default from v22; write it explicitly on v20/21)
Legacy component mutating objects in place — fix the mutation, do not downgrade to Eager
Zone.js
Zoneless (default on v21+; provideZonelessChangeDetection() on v20)
A third-party library that only updates inside a zone — wrap its callbacks in markForCheck() instead of restoring zone.js
Long list
Server-side pagination
Data genuinely must be client-side → CDK virtual scroll above ~100 rows
Heavy below-the-fold widget
@defer (on viewport; prefetch on idle)
It is the LCP element — then it must not be deferred at all
Budget failure in CI
Fix the import; budgets exist to be enforced
The app genuinely grew a feature → raise the budget in the same PR, with the number in the description
2. Measure before anything else
Symptom
Tool
The number you report
Interaction feels slow
Angular DevTools → Profiler (record one interaction)
Change-detection cycles per interaction; slowest component and its ms
Slow first load
Lighthouse on a throttled profile; ng build --stats-json + an esbuild bundle analyzer
LCP, initial bundle bytes, number of eager chunks
Typing/scrolling jank, poor INP
Chrome Performance panel; the web-vitals library reporting INP from real users
Long tasks > 50 ms and what sits in them
Memory grows across routes
DevTools heap snapshots, two navigations apart
Retained component instances and subscriptions
Layout shift
Lighthouse CLS
Elements without reserved dimensions
Record the baseline as a number with its conditions (build, device class, network profile) before touching code, and repeat the same measurement after. "Feels faster" is not a result. Full tool recipes, INP attribution and Lighthouse CI budgets: references/measure-and-profile.md.
3. Change detection and template work
OnPush everywhere. It is the v22 default, so its absence from a decorator is not a defect — but a component that breaks under OnPush is mutating state in place, and that is the actual bug.
Signals for component state, so Angular marks only the components that read the changed signal instead of a subtree.
Zoneless removes change detection on every setTimeout, fetch and mouse move. In zoneless mode Angular is notified by signal writes read in templates, template/host listeners, ChangeDetectorRef.markForCheck() (which AsyncPipe calls), and ComponentRef.setInput — OnPush is recommended but not required, so a Default-strategy component that notifies correctly still works.
No function calls in bindings.{{ format(item) }} runs on every check. Use a computed(), a pure pipe, or @let value = expensive(); when the same value is read several times in one view.
@for needs track on a stable id.track $index on a reorderable list destroys and rebuilds DOM on every move.
Never pure: false on a pipe for formatting — an impure pipe runs on every check, in every row.
ExpressionChangedAfterItHasBeenChecked (NG0100) means state changed during the check — almost always a write in ngAfterViewInit or a child emitting to a parent mid-check. Fix the direction of the data flow; setTimeout only hides it.
4. Bundle and first load
Lazy-load every feature route (loadChildren / loadComponent); the initial chunk holds the shell, auth and the landing route only.
@defer for heavy, below-the-fold or interaction-gated content. Triggers: on idle, on viewport, on interaction, on hover, on immediate, on timer, when <expr>; add ; prefetch on idle (or prefetch on viewport) so the chunk is warm before it is needed. Always give it @placeholder with reserved height — a @defer without one trades JavaScript for layout shift.
Budgets in angular.json (initial ~500 kB warning / ~1 MB error by default; set yours to today's size plus a small margin) and fail CI on breach — a budget that only warns is a log line nobody reads.
Analyse --stats-json output for the usual offenders: a whole date library for one format call, all of lodash, an entire icon font, a chart library on a route that renders one sparkline, Material modules imported at the root.
Images:NgOptimizedImage — ngSrc with width/height or fill, priority on the LCP image only (it sets fetchpriority="high"), sizes for responsive art, and a CDN loader (provideImgixLoader, provideCloudinaryLoader, provideCloudflareLoader, provideImageKitLoader, provideNetlifyLoader, or IMAGE_LOADER for your own).
Fonts: one preloaded subset with font-display: swap. Third-party scripts: deferred, measured, and removed when the measurement does not justify them — they are the entire INP problem more often than app code.
SSR, hydration, TransferCache and prerendering move first-load numbers more than anything here: that is angular-ssr.
5. Lists, tables and network
CDK virtual scroll (cdk-virtual-scroll-viewport + *cdkVirtualFor) above ~100 rows; a fixed itemSize where the design allows. Row components OnPush with signal inputs and no function calls in the row template.
Debounce filter input with debounceTime(300) + distinctUntilChanged() + switchMap so stale requests cancel, while echoing the typed text immediately.
Deduplicate requests: httpResource()/resource() reload on parameter change rather than on every render; for shared observables use shareReplay({ bufferSize: 1, refCount: true }) — without refCount the source never completes and the cached value never frees.
Every manual subscribe() needs takeUntilDestroyed(). Missing teardown is the most common Angular memory leak by a wide margin.
Heavy synchronous work (sorting 50 k rows, parsing, crypto) belongs in a Web Worker; DOM reads belong in afterNextRender({ read: … }), never setTimeout(0).
Virtual-scroll recipes, table strategies, worker setup and content-visibility: references/rendering-and-lists.md.
6. Deliverable format
## Baseline — metric: value (production build, device, network profile)
## Bucket — change detection | template work | bundle | network
## Findings — ordered by impact: problem, the profiler/analyzer evidence, estimated gain
## Fixes — smallest diff per finding, with the expected before/after number
## Verify — the same measurement, repeated, with the result
Checklist
A baseline number exists, taken on a production build, with its conditions stated
The bucket is named before any fix is proposed
Each finding cites evidence (profiler frame, bundle entry, heap diff) rather than a guess
OnPush/signals confirmed; no function calls or new Date() in hot bindings
Every @for has track on a stable id; long lists paginate or virtualise
Heavy routes and widgets are lazy or @deferred with a sized @placeholder
LCP image uses NgOptimizedImage with priority; no other image claims priority
Bundle budgets fail the build, and any raise is justified in the PR
Every subscription has teardown; no shareReplay without refCount
The same measurement was repeated after the fix and is reported
Anti-patterns
provideZoneChangeDetection() left in a v21+ app → delete it; it overrides the zoneless default and reinstates whole-tree checks.
setTimeout to silence NG0100 → fix the data flow: derive upward with computed(), emit downward-to-upward with output().
track $index on reorderable rows → track item.id; index tracking rebuilds the DOM on every move.
Impure pipe or method call for formatting in a row template → computed() on the row's view model, or a pure pipe.
@defer on the LCP element → render it eagerly with priority; deferring it makes LCP worse, not better.
Raising the bundle budget to make CI pass → find what grew in --stats-json first; raise it only with the reason in the PR description.
subscribe() in ngOnInit with no teardown → takeUntilDestroyed(), or toSignal()/httpResource() which clean up themselves.
Rendering 10 000 rows "because virtual scroll is complicated" → server pagination is usually simpler than both and fixes the payload too.
Go deeper
references/measure-and-profile.md — Angular DevTools profiler and signal graph, --stats-json analysis, INP attribution with web-vitals, Lighthouse CI budgets, heap-snapshot workflow
references/rendering-and-lists.md — virtual scroll and table recipes, Web Workers, content-visibility, afterNextRender measurement, zone-only escape hatches
version-notes.md in ../angular-development/references/ — what is default in v20, v21 and v22
Siblings: angular-ssr (hydration, TransferCache, prerender), angular-development (writing the fixed code), angular-architecture (lazy routes, state scope), angular-testing
---
name: angular-performance
description: Diagnose and fix Angular runtime and load performance — change detection doing too much work, template work on every check, oversized bundles, slow LCP and high INP, janky lists and tables, memory growth from undisposed subscriptions. Use this whenever the user says an Angular app is slow, laggy or stutters, reports high TTFB/LCP/INP/CLS or a failing Lighthouse score, sees long tasks or a growing heap, has a table or list that drags while scrolling or typing, hits a bundle-budget error in `ng build`, or asks how to profile with Angular DevTools, `--stats-json`, `@defer`, `track`, virtual scroll or `NgOptimizedImage`. Also use it when a "slow API" turns out to be a client-side waterfall; for SSR, hydration and TransferCache use angular-ssr.
metadata:
technology: Angular
type: performance
---
# Angular Performance
> **Targets:** Angular 22 (LTS 20 and 21 noted where different) · **Verified:** 2026-09 against https://angular.dev/guide/zoneless, https://angular.dev/guide/templates/defer, https://angular.dev/guide/image-optimization
Every Angular performance complaint belongs to one of four buckets: **change detection running too often**, **templates doing work on every check**, **too much JavaScript shipped**, or **the network** (waterfalls, refetches, unbounded data). Measure first, name the bucket, then fix. A fix applied to the wrong bucket costs a sprint and changes nothing.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Where to start | Reproduce on a production build (`ng build` then serve the output) and record a baseline number | Never skip. Dev-mode numbers include double change detection and unminified code |
| Which bucket | Angular DevTools Profiler if interaction is slow; Lighthouse + bundle analysis if first load is slow | A growing heap across navigations → DevTools heap snapshots instead |
| Change-detection strategy | `OnPush` (the framework default from v22; write it explicitly on v20/21) | Legacy component mutating objects in place — fix the mutation, do not downgrade to `Eager` |
| Zone.js | Zoneless (default on v21+; `provideZonelessChangeDetection()` on v20) | A third-party library that only updates inside a zone — wrap its callbacks in `markForCheck()` instead of restoring zone.js |
| Long list | Server-side pagination | Data genuinely must be client-side → CDK virtual scroll above ~100 rows |
| Heavy below-the-fold widget | `@defer (on viewport; prefetch on idle)` | It is the LCP element — then it must not be deferred at all |
| Budget failure in CI | Fix the import; budgets exist to be enforced | The app genuinely grew a feature → raise the budget in the same PR, with the number in the description |
## 2. Measure before anything else
| Symptom | Tool | The number you report |
|---|---|---|
| Interaction feels slow | Angular DevTools → Profiler (record one interaction) | Change-detection cycles per interaction; slowest component and its ms |
| Slow first load | Lighthouse on a throttled profile; `ng build --stats-json` + an esbuild bundle analyzer | LCP, initial bundle bytes, number of eager chunks |
| Typing/scrolling jank, poor INP | Chrome Performance panel; the `web-vitals` library reporting INP from real users | Long tasks > 50 ms and what sits in them |
| Memory grows across routes | DevTools heap snapshots, two navigations apart | Retained component instances and subscriptions |
| Layout shift | Lighthouse CLS | Elements without reserved dimensions |
Record the baseline as a number with its conditions (build, device class, network profile) before touching code, and repeat the same measurement after. "Feels faster" is not a result. Full tool recipes, INP attribution and Lighthouse CI budgets: `references/measure-and-profile.md`.
## 3. Change detection and template work
1. **`OnPush` everywhere.** It is the v22 default, so its absence from a decorator is not a defect — but a component that breaks under `OnPush` is mutating state in place, and that is the actual bug.
2. **Signals for component state**, so Angular marks only the components that read the changed signal instead of a subtree.
3. **Zoneless** removes change detection on every `setTimeout`, `fetch` and mouse move. In zoneless mode Angular is notified by signal writes read in templates, template/host listeners, `ChangeDetectorRef.markForCheck()` (which `AsyncPipe` calls), and `ComponentRef.setInput` — `OnPush` is recommended but not required, so a Default-strategy component that notifies correctly still works.
4. **No function calls in bindings.** `{{ format(item) }}` runs on every check. Use a `computed()`, a pure pipe, or `@let value = expensive();` when the same value is read several times in one view.
5. **`@for` needs `track` on a stable id.** `track $index` on a reorderable list destroys and rebuilds DOM on every move.
6. **Never `pure: false`** on a pipe for formatting — an impure pipe runs on every check, in every row.
7. `ExpressionChangedAfterItHasBeenChecked` (NG0100) means state changed during the check — almost always a write in `ngAfterViewInit` or a child emitting to a parent mid-check. Fix the direction of the data flow; `setTimeout` only hides it.
## 4. Bundle and first load
- **Lazy-load every feature route** (`loadChildren` / `loadComponent`); the initial chunk holds the shell, auth and the landing route only.
- **`@defer`** for heavy, below-the-fold or interaction-gated content. Triggers: `on idle`, `on viewport`, `on interaction`, `on hover`, `on immediate`, `on timer`, `when <expr>`; add `; prefetch on idle` (or `prefetch on viewport`) so the chunk is warm before it is needed. Always give it `@placeholder` with reserved height — a `@defer` without one trades JavaScript for layout shift.
- **Budgets in `angular.json`** (`initial` ~500 kB warning / ~1 MB error by default; set yours to today's size plus a small margin) and fail CI on breach — a budget that only warns is a log line nobody reads.
- **Analyse `--stats-json` output** for the usual offenders: a whole date library for one format call, all of lodash, an entire icon font, a chart library on a route that renders one sparkline, Material modules imported at the root.
- **Images:** `NgOptimizedImage` — `ngSrc` with `width`/`height` or `fill`, `priority` on the LCP image only (it sets `fetchpriority="high"`), `sizes` for responsive art, and a CDN loader (`provideImgixLoader`, `provideCloudinaryLoader`, `provideCloudflareLoader`, `provideImageKitLoader`, `provideNetlifyLoader`, or `IMAGE_LOADER` for your own).
- **Fonts:** one preloaded subset with `font-display: swap`. **Third-party scripts:** deferred, measured, and removed when the measurement does not justify them — they are the entire INP problem more often than app code.
- SSR, hydration, TransferCache and prerendering move first-load numbers more than anything here: that is `angular-ssr`.
## 5. Lists, tables and network
- CDK virtual scroll (`cdk-virtual-scroll-viewport` + `*cdkVirtualFor`) above ~100 rows; a fixed `itemSize` where the design allows. Row components `OnPush` with signal inputs and no function calls in the row template.
- Debounce filter input with `debounceTime(300)` + `distinctUntilChanged()` + `switchMap` so stale requests cancel, while echoing the typed text immediately.
- Deduplicate requests: `httpResource()`/`resource()` reload on parameter change rather than on every render; for shared observables use `shareReplay({ bufferSize: 1, refCount: true })` — without `refCount` the source never completes and the cached value never frees.
- Every manual `subscribe()` needs `takeUntilDestroyed()`. Missing teardown is the most common Angular memory leak by a wide margin.
- Heavy synchronous work (sorting 50 k rows, parsing, crypto) belongs in a Web Worker; DOM reads belong in `afterNextRender({ read: … })`, never `setTimeout(0)`.
Virtual-scroll recipes, table strategies, worker setup and `content-visibility`: `references/rendering-and-lists.md`.
## 6. Deliverable format
```
## Baseline — metric: value (production build, device, network profile)
## Bucket — change detection | template work | bundle | network
## Findings — ordered by impact: problem, the profiler/analyzer evidence, estimated gain
## Fixes — smallest diff per finding, with the expected before/after number
## Verify — the same measurement, repeated, with the result
```
## Checklist
- [ ] A baseline number exists, taken on a production build, with its conditions stated
- [ ] The bucket is named before any fix is proposed
- [ ] Each finding cites evidence (profiler frame, bundle entry, heap diff) rather than a guess
- [ ] `OnPush`/signals confirmed; no function calls or `new Date()` in hot bindings
- [ ] Every `@for` has `track` on a stable id; long lists paginate or virtualise
- [ ] Heavy routes and widgets are lazy or `@defer`red with a sized `@placeholder`
- [ ] LCP image uses `NgOptimizedImage` with `priority`; no other image claims priority
- [ ] Bundle budgets fail the build, and any raise is justified in the PR
- [ ] Every subscription has teardown; no `shareReplay` without `refCount`
- [ ] The same measurement was repeated after the fix and is reported
## Anti-patterns
- **`provideZoneChangeDetection()` left in a v21+ app** → delete it; it overrides the zoneless default and reinstates whole-tree checks.
- **`setTimeout` to silence NG0100** → fix the data flow: derive upward with `computed()`, emit downward-to-upward with `output()`.
- **`track $index` on reorderable rows** → `track item.id`; index tracking rebuilds the DOM on every move.
- **Impure pipe or method call for formatting in a row template** → `computed()` on the row's view model, or a pure pipe.
- **`@defer` on the LCP element** → render it eagerly with `priority`; deferring it makes LCP worse, not better.
- **Raising the bundle budget to make CI pass** → find what grew in `--stats-json` first; raise it only with the reason in the PR description.
- **`subscribe()` in `ngOnInit` with no teardown** → `takeUntilDestroyed()`, or `toSignal()`/`httpResource()` which clean up themselves.
- **Rendering 10 000 rows "because virtual scroll is complicated"** → server pagination is usually simpler than both and fixes the payload too.
## Go deeper
- `references/measure-and-profile.md` — Angular DevTools profiler and signal graph, `--stats-json` analysis, INP attribution with `web-vitals`, Lighthouse CI budgets, heap-snapshot workflow
- `references/rendering-and-lists.md` — virtual scroll and table recipes, Web Workers, `content-visibility`, `afterNextRender` measurement, zone-only escape hatches
- `version-notes.md` in `../angular-development/references/` — what is default in v20, v21 and v22
- Siblings: `angular-ssr` (hydration, TransferCache, prerender), `angular-development` (writing the fixed code), `angular-architecture` (lazy routes, state scope), `angular-testing`