Org Skills

angular-performance

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill angular-performance
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill angular-performance -g

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.

Skill contents

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 @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

References

Deeper material the agent loads only when needed.