Performance guidelines
Purpose: The performance budget and the AEM-specific rules that keep render times and cache ratios healthy.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| All engineers | Performance is a feature requirement, not a tuning phase |
Budgets (adopt and adjust)
| Metric | Budget |
|---|---|
| Publish render time (uncached page) | p95 < 500ms |
| Dispatcher/CDN cache hit ratio (HTML) | > 90% |
| Page weight (PHI plan page class) | < 1.5MB, < 60 requests |
| Third-party JS | < 200KB, zero render-blocking |
| Core Web Vitals | LCP < 2.5s, INP < 200ms, CLS < 0.1 |
Server-side rules
- The cache is the performance strategy: maximise cacheability first, optimise render second. A 2× faster render on a 95% cached site moves p95 barely; +4% hit ratio moves everything.
- No external HTTP on the render path (integration placement).
- No unbounded queries or child iteration over huge trees per render; models compute once in @PostConstruct.
- Watch session/resolver leaks — they degrade instances slowly (error.log warnings tell you).
- Component renders must be user-independent (cacheable); personalisation client-side.
Frontend rules
- Versioned clientlibs + long TTLs; vendor split from app bundle for cache stability.
- Images via renditions/adaptive servlet with srcset — never originals; lazy-load below the fold.
- CSS in head, JS deferred at body end; no @import chains; fonts with font-display swap and preload.
- Measure per PR where feasible (Lighthouse CI against a stage URL) — budgets enforced by pipeline beat budgets in a wiki.
When it's already slow
Diagnosis order and tooling: Memory & CPU issues and Slow queries in the Troubleshooting Hub.