Frontend Performance
Backend latency is measured in milliseconds at the load balancer. Frontend performance is measured on the user's device: a mid-range Android phone on a congested 4G connection, with a CPU four to six times slower than your laptop. The time from "user taps a link" to "user can read and use the page" is dominated not by your API, but by what happens after the first byte arrives — how many bytes of JavaScript must be downloaded, parsed and executed, how soon the largest image paints, and whether the main thread is free when the user taps a button.
This page is the overview: what to measure, where the time goes, and which levers matter most. The deeper treatments live in Frontend Engineering — this page links to them rather than repeating them.
Where Frontend Time Goes
flowchart LR
NAV["Navigation"] --> DNS["DNS + TCP + TLS"]
DNS --> TTFB["TTFB<br/>(server / CDN)"]
TTFB --> HTML["HTML parse"]
HTML --> CSS["Render-blocking<br/>CSS"]
HTML --> JS["JS download,<br/>parse, execute"]
CSS --> FCP["First Contentful Paint"]
HTML --> IMG["LCP resource<br/>(image / font)"]
IMG --> LCP["Largest Contentful Paint"]
JS --> HYD["Hydration /<br/>event handlers"]
HYD --> INT["Page responds to input<br/>(INP)"]
| Phase | Typical share on a slow device | Main levers |
|---|---|---|
| Connection + TTFB | 10-30% | CDN, edge caching, HTTP/3, server render time |
| Resource discovery and download | 20-40% | Preload, priority hints, image formats, compression |
| JavaScript parse/compile/execute | 30-50% | Ship less JS, code-split, defer, avoid hydration cost |
| Layout, paint, layout shifts | 5-15% | Reserve space, avoid layout thrashing, CSS containment |
Most sites that fail Core Web Vitals fail because of the third row. The single most effective frontend performance strategy is shipping less JavaScript.
Core Web Vitals
Core Web Vitals are three user-centric metrics Google uses in search ranking and Chrome reports from real users. Each is evaluated at the 75th percentile of page loads, split by mobile and desktop.
| Metric | Measures | Good | Needs improvement | Poor |
|---|---|---|---|---|
| LCP — Largest Contentful Paint | Loading: when the main content renders | ≤ 2.5s | 2.5-4.0s | > 4.0s |
| INP — Interaction to Next Paint | Responsiveness: worst-ish input-to-paint latency over the visit | ≤ 200ms | 200-500ms | > 500ms |
| CLS — Cumulative Layout Shift | Visual stability: unexpected movement of content | ≤ 0.1 | 0.1-0.25 | > 0.25 |
INP replaced First Input Delay (FID) in March 2024. FID only measured the delay before the first interaction's handler ran; INP measures the full latency (input delay + processing + presentation) across all interactions and reports roughly the worst one. Sites that passed FID easily often fail INP.
Supporting diagnostics that are not Core Web Vitals but explain them:
| Metric | Why it matters |
|---|---|
| TTFB (Time to First Byte) | Lower bound on LCP; target ≤ 800ms |
| FCP (First Contentful Paint) | Gap between FCP and LCP reveals late-discovered LCP resources |
| TBT (Total Blocking Time) | Lab proxy for INP: sum of long-task time over 50ms |
| Long Animation Frames (LoAF) | Field attribution for slow frames — which script caused INP |
Element-level detail on each metric — what qualifies as the LCP element, how INP is computed, CLS session windows — is in Web Performance & Core Web Vitals.
LCP Breakdown
LCP is not one number to optimize; it is four sub-parts, and each has a different fix:
LCP = TTFB
+ resource load delay (time from TTFB until the browser STARTS fetching the LCP resource)
+ resource load duration (time to download it)
+ element render delay (time from download complete until it paints)
| Sub-part | Healthy share | If it is large |
|---|---|---|
| TTFB | ~40% | Cache HTML at the edge, speed up server render |
| Resource load delay | < 10% | LCP image is discovered late: lazy-loaded, set by JS, or a CSS background — preload it and add fetchpriority="high" |
| Resource load duration | ~40% | Image too large: modern format, correct srcset sizes, CDN |
| Element render delay | < 10% | Render-blocking JS/CSS, client-side rendering, or a font blocking text paint |
INP Breakdown
INP = input delay (main thread busy with other work when the user interacts)
+ processing time (your event handlers + framework re-render)
+ presentation delay (style, layout, paint of the next frame)
The fixes are main-thread fixes: break up long tasks, yield inside expensive handlers, reduce re-render scope, and avoid giant DOM trees.
// Yield to the browser so it can paint feedback before heavy work continues
async function yieldToMain(): Promise<void> {
// scheduler.yield() keeps the task's priority; fall back to a macrotask
const s = (globalThis as { scheduler?: { yield?: () => Promise<void> } }).scheduler;
if (s?.yield) return s.yield();
return new Promise((resolve) => setTimeout(resolve, 0));
}
button.addEventListener("click", async () => {
button.setAttribute("aria-busy", "true"); // immediate visual feedback
await yieldToMain(); // let that frame paint
const results = applyFilters(allRows); // heavy work after the paint
await yieldToMain();
renderResults(results);
button.removeAttribute("aria-busy");
});
CLS Causes
| Cause | Fix |
|---|---|
| Images/iframes/ads without dimensions | width/height attributes or CSS aspect-ratio |
| Web fonts swapping with different metrics | size-adjust, ascent-override on the fallback @font-face; font-display: optional |
| Content injected above existing content (banners, consent bars) | Reserve space, or overlay instead of push |
Animating top/height/margin | Animate transform and opacity only |
| Late-loading embeds | Fixed-size placeholder containers |
Field vs Lab
| Field (RUM) | Lab (synthetic) | |
|---|---|---|
| Source | Real users' browsers | A controlled run (Lighthouse, WebPageTest) |
| Tools | CrUX, web-vitals library, RUM vendors | Lighthouse, WebPageTest, Chrome DevTools Performance panel |
| INP | Yes — needs real interactions | No; use TBT as a proxy |
| Strength | Truth: what users experience, used for ranking | Reproducible, debuggable, runs in CI |
| Weakness | Noisy; needs traffic; 28-day lag in CrUX | Not representative of real devices/networks |
Use field data to decide what to fix and lab data to find out why and to prevent regressions. A Lighthouse score of 98 on a developer laptop says nothing about p75 INP on low-end Android.
Measuring in the Field
// rum.ts — report Core Web Vitals with attribution to your analytics endpoint
import { onCLS, onINP, onLCP, onTTFB, type Metric } from "web-vitals/attribution";
function send(metric: Metric) {
const body = JSON.stringify({
name: metric.name,
value: metric.value,
rating: metric.rating, // "good" | "needs-improvement" | "poor"
id: metric.id,
navigationType: metric.navigationType,
page: location.pathname,
// Attribution tells you WHY: LCP element, slow INP target, shifting node
attribution: summarize(metric),
});
// sendBeacon survives page unload; fall back to keepalive fetch
if (!navigator.sendBeacon?.("/rum", body)) {
fetch("/rum", { method: "POST", body, keepalive: true });
}
}
function summarize(metric: Metric): Record<string, unknown> {
const a = (metric as Metric & { attribution?: Record<string, unknown> }).attribution ?? {};
switch (metric.name) {
case "LCP":
return { target: a.target, url: a.url, loadDelay: a.resourceLoadDelay, renderDelay: a.elementRenderDelay };
case "INP":
return { target: a.interactionTarget, type: a.interactionType, inputDelay: a.inputDelay, processing: a.processingDuration };
case "CLS":
return { target: a.largestShiftTarget, time: a.largestShiftTime };
default:
return {};
}
}
onLCP(send);
onINP(send);
onCLS(send);
onTTFB(send);
Aggregate at p75 per route and device class. Segmenting by route is essential — a fast marketing page averaged with a slow dashboard hides both.
# Origin-level field data from the Chrome UX Report API
curl -s "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$CRUX_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"origin": "https://www.example.com", "formFactor": "PHONE",
"metrics": ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"]}' \
| jq '.record.metrics | map_values(.percentiles.p75)'
The Critical Rendering Path
The browser cannot paint until it has the DOM and the CSSOM for what is on screen. Anything that delays either delays first paint and usually LCP.
flowchart TD
H["HTML bytes"] --> T["Tokenize & parse"] --> DOM["DOM"]
C["CSS bytes"] --> CP["Parse CSS"] --> CSSOM["CSSOM"]
DOM --> RT["Render tree<br/>(visible nodes + computed style)"]
CSSOM --> RT
RT --> L["Layout"] --> P["Paint"] --> CO["Composite"]
S["Sync script"] -. "blocks parser" .-> T
C -. "blocks render<br/>and blocks sync scripts" .-> S
| Resource | Default behaviour | Make it non-blocking |
|---|---|---|
<link rel="stylesheet"> in head | Render-blocking | Inline critical CSS; load the rest with media swap or per-route CSS |
<script src> without attributes | Parser-blocking | defer (ordered, after parse) or type="module" (deferred by default) |
<script async> | Runs whenever downloaded, blocks parser at that moment | Use for independent scripts (analytics) only |
| Web fonts | Text invisible up to 3s in most browsers (font-display: auto) | font-display: swap or optional, preload the critical file |
| Images | Not blocking, but LCP waits on them | fetchpriority="high" on LCP, loading="lazy" below the fold |
Rendering pipeline internals — style recalc, layout, paint, compositing layers, and layout thrashing — are covered in Browser Rendering Pipeline.
A Well-Ordered Head
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<!-- 1. Connect early to critical third-party origins -->
<link rel="preconnect" href="https://cdn.example.com" crossorigin />
<!-- 2. Inline critical, above-the-fold CSS (keep under ~14KB) -->
<style>/* critical rules for header, hero, layout */</style>
<!-- 3. Fetch the LCP image and the critical font immediately -->
<link rel="preload" as="image" href="/hero-1200.avif"
imagesrcset="/hero-800.avif 800w, /hero-1200.avif 1200w"
imagesizes="100vw" fetchpriority="high" />
<link rel="preload" as="font" type="font/woff2"
href="/fonts/inter-var-latin.woff2" crossorigin />
<!-- 4. Full stylesheet -->
<link rel="stylesheet" href="/assets/app.3f9a1c.css" />
<!-- 5. App code: deferred, never parser-blocking -->
<script type="module" src="/assets/app.8b21de.js"></script>
</head>
Resource Hints
| Hint | Use for | Cost of misuse |
|---|---|---|
preconnect | 1-3 critical cross-origin hosts (CDN, API) | Wasted sockets if unused |
dns-prefetch | Less critical cross-origin hosts | Negligible |
preload | Late-discovered critical resources (LCP image, fonts, CSS-referenced assets) | Competes with other critical resources; console warning if unused |
modulepreload | Critical ES module dependencies | Same as preload |
prefetch | Resources for the next navigation | Wasted bandwidth on metered connections |
Speculation Rules (prerender) | Near-instant next-page navigations | Server load and analytics double-counting |
fetchpriority | Raise LCP image, lower carousel images | Raising everything is the same as raising nothing |
Serve the First Bytes Fast
Nothing on this page matters if HTML takes two seconds to arrive. Cache HTML at the CDN where possible, use stale-while-revalidate, and consider moving rendering to the edge — see HTTP Caching, Edge Caching and Edge Computing. HTTP 103 Early Hints lets the CDN send preload hints while the origin is still rendering.
Bundle Optimization
JavaScript is the most expensive byte on the web: unlike an image, it must be downloaded, decompressed, parsed, compiled and executed on the main thread. 300KB of compressed JS can be 1MB+ uncompressed and cost 1-2 seconds of CPU on a mid-range phone.
The Levers, in Order of Impact
| Lever | Typical saving | Notes |
|---|---|---|
| Remove or replace heavy dependencies | 20-60% | moment → date-fns/Temporal, full lodash → per-method imports, chart libraries loaded on demand |
| Route-based code splitting | 30-70% of initial JS | Each route loads only what it needs |
| Lazy-load below-the-fold / interaction-only components | 10-30% | Modals, editors, maps, charts |
Tree shaking with correct sideEffects | 5-30% | Requires ESM and side-effect-free modules |
| Server components / islands (ship no JS for static UI) | 30-90% | Architectural; see rendering strategies below |
| Modern-only builds (no ES5 transpilation, minimal polyfills) | 10-20% | Target browsers you actually serve |
| Brotli compression | 15-25% smaller than gzip | Pre-compress static assets at build time |
// Route-level splitting (React Router + lazy)
import { lazy, Suspense } from "react";
import { createBrowserRouter } from "react-router-dom";
const Dashboard = lazy(() => import("./routes/Dashboard"));
const Reports = lazy(() => import("./routes/Reports")); // pulls charting lib only here
export const router = createBrowserRouter([
{ path: "/", element: <Suspense fallback={<PageSkeleton />}><Dashboard /></Suspense> },
{ path: "/reports", element: <Suspense fallback={<PageSkeleton />}><Reports /></Suspense> },
]);
// Interaction-triggered loading: the editor's 400KB loads only when needed
async function openEditor(container: HTMLElement) {
const { createEditor } = await import("./editor");
createEditor(container);
}
// Warm it up on intent (hover/focus) so the click feels instant
editButton.addEventListener("pointerenter", () => void import("./editor"), { once: true });
editButton.addEventListener("click", () => openEditor(panel));
Tree-shaking failure modes, vendor chunking strategy, bundle analysis tooling, and compression configuration are covered in Bundle Optimization.
Third-Party Scripts
Tag managers, chat widgets, A/B testing and analytics are frequently the largest source of main-thread work on commercial sites — and the one engineering teams control least.
- Audit them quarterly with the Coverage and Performance panels; every tag needs an owner.
- Load non-essential tags after
loador on interaction; use facades (a static placeholder) for chat and video embeds. - Client-side A/B testing that hides the page until the experiment loads directly damages LCP — move experiments server-side or to the edge.
- Consider moving analytics off the main thread (Partytown or server-side tagging).
Images and Fonts
Image Strategy
Images are usually the LCP element and the largest share of page bytes.
| Decision | Recommendation |
|---|---|
| Format | AVIF first, WebP fallback, JPEG last; SVG for icons and illustrations |
| Sizing | srcset + accurate sizes, so phones never download desktop images |
| LCP image | Never lazy-load; fetchpriority="high"; in initial HTML (not injected by JS) |
| Below-the-fold | loading="lazy" and decoding="async" |
| Dimensions | Always set width/height (or aspect-ratio) to prevent CLS |
| Delivery | Image CDN that negotiates format via Accept and resizes on the fly |
<picture>
<source type="image/avif"
srcset="/img/hero-640.avif 640w, /img/hero-1024.avif 1024w, /img/hero-1600.avif 1600w"
sizes="(max-width: 768px) 100vw, 1200px" />
<source type="image/webp"
srcset="/img/hero-640.webp 640w, /img/hero-1024.webp 1024w, /img/hero-1600.webp 1600w"
sizes="(max-width: 768px) 100vw, 1200px" />
<img src="/img/hero-1024.jpg" alt="Team reviewing a dashboard"
width="1600" height="900" fetchpriority="high" decoding="async" />
</picture>
Font Strategy
| Decision | Recommendation |
|---|---|
| Format | WOFF2 only |
| Hosting | Self-host on your own origin/CDN (avoids extra connection; no cross-site cache benefit exists anymore) |
| Subsetting | Subset by unicode-range (e.g. Latin vs Latin Extended) |
| Variable fonts | One variable file usually beats 4+ static weights |
| Display | swap for brand fonts in body text; optional when CLS matters most |
| Fallback metrics | Tune fallback with size-adjust / ascent-override to eliminate swap shift |
| Preload | Only the 1-2 files used above the fold |
@font-face {
font-family: "Inter";
src: url("/fonts/inter-var-latin.woff2") format("woff2");
font-weight: 100 900;
font-display: swap;
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+2000-206F;
}
/* Metric-matched fallback: text does not move when Inter arrives */
@font-face {
font-family: "Inter Fallback";
src: local("Arial");
size-adjust: 107%;
ascent-override: 90%;
descent-override: 22%;
line-gap-override: 0%;
}
body {
font-family: "Inter", "Inter Fallback", system-ui, sans-serif;
}
Format comparisons, lazy-loading strategy and font display trade-offs in more depth are in Web Performance & Core Web Vitals.
Rendering Strategies and Performance
Where HTML is produced determines which metrics are easy and which are hard.
flowchart TD
Q1{"Is the content the same<br/>for every user?"} -- Yes --> Q2{"How often does it change?"}
Q2 -- "Rarely / on deploy" --> SSG["SSG<br/>prebuilt at build time"]
Q2 -- "Minutes to hours" --> ISR["ISR / CDN cache + revalidate"]
Q1 -- "No, personalized" --> Q3{"Does it need SEO and<br/>fast first paint?"}
Q3 -- Yes --> Q4{"Are some parts slow<br/>(slow APIs)?"}
Q4 -- Yes --> STR["Streaming SSR<br/>shell first, slow parts stream in"]
Q4 -- No --> SSR["SSR"]
Q3 -- "No, behind login, app-like" --> CSR["CSR<br/>(SPA)"]
| Strategy | TTFB | LCP | INP risk | Server cost | Typical fit |
|---|---|---|---|---|---|
| CSR | Excellent (static shell) | Poor — waits for JS + API | High — big bundles | Lowest | Authenticated dashboards, internal tools |
| SSR | Depends on server/API latency | Good | Medium — hydration cost | Highest per request | Personalized, SEO-relevant pages |
| SSG | Excellent (CDN) | Excellent | Medium — hydration cost | Build time only | Docs, marketing, blogs |
| ISR | Excellent (CDN, mostly hits) | Excellent | Medium | Low | Catalogs, listings, content sites with frequent updates |
| Streaming SSR | Excellent (shell flushes early) | Good-excellent | Medium | High | Pages mixing fast and slow data |
| Server Components / islands | As SSR/SSG | Excellent | Low — little or no JS for static parts | As SSR/SSG | Content-heavy pages with small interactive regions |
Key performance observations:
- SSR does not fix INP. A server-rendered page that hydrates 500KB of JavaScript looks ready but ignores taps until hydration finishes. This "uncanny valley" often produces worse INP than CSR with a skeleton.
- Hydration is the hidden cost. Islands architecture (Astro, Fresh), React Server Components and resumability (Qwik) all exist to avoid shipping and executing JS for static content.
- CSR's LCP problem is a waterfall. HTML → JS → fetch data → render. SSR, SSG and streaming collapse it; for CSR, at minimum preload the data request and the LCP image.
- Streaming wins when data latency is uneven. Flush the shell and the LCP content immediately; stream recommendations or comments behind Suspense boundaries.
// Streaming SSR with React Server Components (Next.js App Router)
import { Suspense } from "react";
export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const product = await getProduct(id); // fast, cached — part of the first flush (LCP)
return (
<main>
<ProductHero product={product} />
{/* Slow personalized data streams in later; does not delay LCP */}
<Suspense fallback={<RecommendationsSkeleton />}>
<Recommendations productId={id} />
</Suspense>
</main>
);
}
Implementation details, framework examples and the full decision matrix are in SSR vs SSG vs ISR vs CSR. For how React schedules rendering and hydration internally, see React Internals.
War Story (illustrative)
An e-commerce team migrated product pages from CSR to SSR to fix LCP. LCP dropped from 4.1s to 2.2s — and INP got worse, from 180ms to 340ms. The server-rendered HTML now painted early, so users tapped "Add to cart" while the 600KB bundle was still hydrating, and those taps queued behind a 900ms hydration task. The fix was not reverting SSR but cutting what hydrated: the product description, reviews and footer became server components with no client JS, the cart button and image gallery stayed interactive, and the initial bundle dropped to 180KB. INP fell to 120ms.
Caching and Repeat Visits
First visits get the attention, but most sessions are repeat visits and client-side navigations. Get these right and the second page load is nearly free.
| Asset | Cache-Control | Why |
|---|---|---|
Hashed JS/CSS/fonts/images (app.8b21de.js) | public, max-age=31536000, immutable | Content-addressed; a new deploy changes the URL |
| HTML documents | public, max-age=0, s-maxage=60, stale-while-revalidate=300 (or no-cache if personalized) | Browser always revalidates; CDN absorbs load |
| API responses used for rendering | Short s-maxage + stale-while-revalidate where data allows | Keeps SSR TTFB low |
Unhashed assets (/logo.png) | Short max-age + ETag | Must be revalidated after changes |
# Static asset server: hashed files are immutable, HTML always revalidates
location ~* "\.[0-9a-f]{8,}\.(js|css|woff2|avif|webp|png|svg)$" {
add_header Cache-Control "public, max-age=31536000, immutable";
gzip_static on;
brotli_static on;
}
location / {
add_header Cache-Control "no-cache";
try_files $uri $uri/ /index.html;
}
Other repeat-visit levers:
- Back/forward cache (bfcache): instant back navigations, but only if the page is eligible.
unloadhandlers andCache-Control: no-storeon the document make pages ineligible — check the "Back/forward cache" panel in DevTools Application tab. - Speculation Rules: prerender likely next pages (for example, the first product in a listing on hover) so the navigation completes in tens of milliseconds.
- Service workers: cache the app shell and static assets for offline and instant repeat loads; avoid putting a slow service worker boot in front of every navigation (use navigation preload).
- Client-side navigation: in SPAs, prefetch route chunks and data on link hover or viewport entry so route transitions do not wait on the network.
<script type="speculationrules">
{
"prerender": [
{ "where": { "href_matches": "/products/*" }, "eagerness": "moderate" }
]
}
</script>
Header semantics, CDN behaviour and invalidation are covered in HTTP Caching and Edge Caching.
Performance Budgets in CI
A one-time optimization project decays within months as features land. Budgets make performance a build constraint, like tests.
What to Budget
| Budget type | Example | Catches |
|---|---|---|
| Size (per route, compressed) | Initial JS ≤ 170KB, CSS ≤ 50KB | Accidental heavy dependencies |
| Request count | ≤ 40 requests on first load | Unbounded third-party growth |
| Lab timings | LCP ≤ 2.5s, TBT ≤ 200ms, CLS ≤ 0.1 on a throttled mobile profile | Rendering and main-thread regressions |
| Field (alerting, not gating) | p75 LCP/INP/CLS per route from RUM | Real-world regressions lab misses |
The ~170KB compressed JS figure is a widely used starting point for a mid-range phone on 4G to reach interactivity in roughly five seconds; tighter budgets are better.
Bundle Size Gate
// .size-limit.json
[
{ "name": "initial JS", "path": "dist/assets/index-*.js", "limit": "170 KB", "gzip": true },
{ "name": "initial CSS", "path": "dist/assets/index-*.css", "limit": "50 KB", "gzip": true },
{ "name": "reports route", "path": "dist/assets/Reports-*.js", "limit": "120 KB", "gzip": true }
]
Lighthouse CI
// lighthouserc.cjs
module.exports = {
ci: {
collect: {
startServerCommand: "npm run preview -- --port 4173",
url: ["http://localhost:4173/", "http://localhost:4173/products/demo", "http://localhost:4173/checkout"],
numberOfRuns: 3, // median of 3 smooths lab noise
},
assert: {
assertions: {
"largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
"total-blocking-time": ["error", { maxNumericValue: 200 }],
"cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
"resource-summary:script:size": ["error", { maxNumericValue: 175000 }],
"unused-javascript": ["warn", { maxLength: 2 }],
"uses-responsive-images": "warn",
"render-blocking-resources": "warn",
},
},
upload: { target: "temporary-public-storage" },
},
};
# .github/workflows/perf-budget.yml
name: performance-budget
on:
pull_request:
paths: ["src/**", "package.json", "package-lock.json", "vite.config.*"]
jobs:
budget:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
- name: Bundle size budget
run: npx size-limit
- name: Lighthouse budget
run: npx @lhci/cli@0.14.x autorun
env:
LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
TIP
Gate on size budgets (deterministic) and TBT/CLS (fairly stable); treat lab LCP as a warning unless your CI runners are dedicated, because shared runners add timing noise. Field metrics from RUM should drive alerts and dashboards, not PR gates.
WARNING
A budget no one is allowed to exceed becomes a budget someone quietly raises. Require a short justification in the PR when a budget changes, and review budget increases the same way you review API changes.
Debugging a Slow Page
flowchart TD
S["Field data shows a poor metric<br/>on route X"] --> W{"Which metric?"}
W -- LCP --> L1["Check LCP attribution:<br/>which element, which sub-part"]
L1 --> L2{"Largest sub-part?"}
L2 -- TTFB --> L3["Server/CDN: cache HTML,<br/>edge render, Early Hints"]
L2 -- "Load delay" --> L4["Preload + fetchpriority,<br/>stop lazy-loading LCP"]
L2 -- "Load duration" --> L5["Smaller image, AVIF,<br/>correct sizes"]
L2 -- "Render delay" --> L6["Remove render-blocking JS/CSS,<br/>move off CSR"]
W -- INP --> I1["LoAF / INP attribution:<br/>which interaction, which script"]
I1 --> I2["Performance panel trace<br/>with 4x CPU throttle"]
I2 --> I3["Break long tasks, yield,<br/>reduce hydration and re-renders"]
W -- CLS --> C1["Layout Shift attribution:<br/>which node moved"]
C1 --> C2["Reserve space, fix font metrics,<br/>stop injecting above content"]
Use the Chrome DevTools Performance panel with 4x CPU throttling and a "Fast 4G" or "Slow 4G" network profile to approximate real devices. The browser-side profiling workflow — reading flame charts, finding long tasks, and attributing them to scripts — is covered in Browser Profiling.
Frontend Performance Checklist
Loading
- HTML cached at the CDN or rendered at the edge; TTFB p75 ≤ 800ms
-
LCP resource in the initial HTML, preloaded,
fetchpriority="high", never lazy-loaded - Critical CSS inlined; no render-blocking third-party CSS
-
All scripts
defer/type="module"; no parser-blocking scripts in head - Brotli for text assets; immutable cache headers on hashed assets
JavaScript
- Initial JS per route within budget (≤ ~170KB compressed)
- Route-level code splitting; heavy widgets loaded on interaction
- Bundle analyzer reviewed each release; no duplicate dependency versions
- Third-party tags owned, audited, and deferred
- Static content shipped without hydration where the framework allows
Responsiveness
- No tasks over 50ms in key interactions on a 4x-throttled profile
-
Expensive handlers yield (
scheduler.yield()orsetTimeout) after visual feedback - Large lists virtualized; DOM size reasonable (< ~1,500 nodes for most pages)
Stability
- Every image, video, iframe and ad slot has reserved dimensions
- Font fallbacks metric-matched
-
Animations use
transform/opacityonly
Process
- RUM collecting LCP/INP/CLS with attribution, segmented by route and device
- Size and Lighthouse budgets enforced in CI
- Alerts on p75 regressions per route
Cross-References
- Web Performance & Core Web Vitals — metrics, images, fonts, third parties in depth
- Bundle Optimization — tree shaking, code splitting, compression
- Browser Rendering Pipeline — the pixel pipeline, layout and compositing
- SSR vs SSG vs ISR vs CSR — rendering strategy implementation and decision matrix
- React Internals — reconciliation, scheduling, hydration
- Browser Profiling — DevTools Performance panel workflow
- HTTP Caching — cache headers for HTML and assets
- Edge Computing — rendering and caching close to users
- Node.js Performance — when the slow part is the SSR server