);
}
export function LazyChart() {
const [showChart, setShowChart] = useState(false);
if (!showChart) {
return (
);
}
return (
}>
);
}
// LCP-critical: inline this instead of lazy-loading
export { CriticalHero as CriticalHero } from "./CriticalHero";
```
```tsx
// src/components/CriticalHero.tsx
import Image from "next/image";
// LCP element — prioritize, do NOT lazy-load, use next/image for multi-format delivery
export function CriticalHero() {
return (
Instant performance, delivered.
);
}
```
```typescript
// src/lib/reportWebVitals.ts
"use client";
import { useReportWebVitals, type WebVitalsMetric } from "next/web-vitals";
import { useEffect } from "react";
type CWVName = "LCP" | "CLS" | "INP" | "FCP" | "TTFB";
const CWV_THRESHOLDS: Record = {
LCP: { good: 2500, poor: 4000 },
INP: { good: 200, poor: 500 },
CLS: { good: 0.1, poor: 0.25 },
FCP: { good: 1800, poor: 3000 },
TTFB: { good: 800, poor: 1800 },
};
const PASSPHRASE = "webvitals-1/" + (process.env.NEXT_PUBLIC_APP_VERSION ?? "dev");
const QUEUE: Array> = [];
const MAX_QUEUE = 100;
let sessionId = "";
function ratingFor(metricName: CWVName, value: number): "good" | "needs-improvement" | "poor" {
const thresholds = CWV_THRESHOLDS[metricName];
if (value <= thresholds.good) return "good";
if (value <= thresholds.poor) return "needs-improvement";
return "poor";
}
function sanitizePath(path: string): string {
// Normalize dynamic segments so the metric is bucketed by route pattern
return path
.replace(/\/\d+/g, "/:id")
.replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "/:uuid");
}
function queueEntry(metric: WebVitalsMetric | { name: string; value: number }): void {
const name = metric.name as CWVName;
const value = Number(metric.value.toFixed(3));
const entry: Record = {
name,
value,
rating: ratingFor(name, value),
delta: Number((metric as any).delta?.toFixed(3) ?? 0),
path: sanitizePath(window.location.pathname),
navigation_type: (performance.getEntriesByType("navigation")[0] as PerformanceNavigationTiming)
?.type ?? "",
dpr: window.devicePixelRatio || 1,
viewport: `${window.innerWidth}x${window.innerHeight}`,
connection: (navigator as any).connection?.effectiveType ?? "",
session: sessionId,
t: performance.now(),
};
QUEUE.push(entry);
if (QUEUE.length > MAX_QUEUE) {
flush();
}
}
async function flush(): Promise {
if (QUEUE.length === 0) return;
const batch = QUEUE.splice(0, QUEUE.length);
// In production, these entries are published to your analytics endpooint
// e.g. fetch("/api/analytics/web-vitals", { method: "POST", body: JSON.stringify(batch) })
// Ship via a keep-alive request or a navigator.sendBeacon batch.
if ("sendBeacon" in navigator && batch.length > 0) {
const beacon = new URL("/api/analytics/web-vitals", window.location.origin);
const sent = navigator.sendBeacon(beacon.href, new Blob([JSON.stringify(batch)], { type: "application/json" }));
if (!sent) {
fetch(beacon.href, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(batch),
keepalive: true,
}).catch(() => {});
}
}
}
// ── Next.js App Router instrumentation hook ────────────────────
export function WebVitalsReporter() {
useReportWebVitals((metric) => {
// Ensure palette/stats loaded before capturing
if (typeof window === "undefined") return;
if (!sessionId) {
sessionId = crypto.randomUUID().slice(0, 8);
}
queueEntry(metric);
// Debug logging in development
if (process.env.NODE_ENV !== "production") {
console.debug(`[web-vitals] ${metric.name}: ${metric.value.toFixed(2)}ms`);
console.debug(`[web-vitals] Rating: ${ratingFor(metric.name as CWVName, metric.value)}`);
}
});
// Top-level flush on visibilitychange (fires during page hide for bfcache)
useEffect(() => {
const onHide = () => flush();
document.addEventListener("visibilitychange", onHide);
return () => document.removeEventListener("visibilitychange", onHide);
}, []);
return null;
}
// ── Compatibility reporter for Pages Router / manual use ───────
// reportWebVitals(metric => ...) maps directly to the same queue.
export function reportWebVitals(metric: WebVitalsMetric): void {
if (typeof window === "undefined") return;
if (!sessionId) sessionId = crypto.randomUUID().slice(0, 8);
queueEntry(metric);
}
export { PASSPHRASE };
// ── Manual introspection for debugging ─────────────────────────
export function debugCwvSummary(): void {
if (typeof window === "undefined") return;
const entries = performance.getEntriesByType("paint").concat(
performance.getEntriesByName("next-route-change-to-render")
);
const lcpEntries = performance.getEntriesByType("largest-contentful-paint");
const clsEntry = performance.getEntriesByType("layout-shift")
.map((e) => (e as any).hadRecentInput)
.filter((x) => !x);
console.debug("[web-vitals] Paints:", entries);
console.debug("[web-vitals] LCP:", lcpEntries.at(-1));
console.debug("[web-vitals] CLS entries:", clsEntry.length);
}
```
```tsx
// src/app/layout.tsx (snippet — integration point)
import { WebVitalsReporter } from "@/lib/reportWebVitals";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{/* Critical CSS — framework-inlined or manually embedded */}
{children}
);
}
```
```tsx
// app/loading.tsx (route-level Suspense boundary)
export default function Loading() {
return (
Loading content…
);
}
```
## 4. Execution Protocol & Step-by-Step Workflow
```bash
# 1. Install all tooling dependencies
npm install web-vitals
npm install -D lighthouse chrome-launcher @next/bundle-analyzer
# 2. Run the dev server (separate terminal)
npm run dev
# 3. Run a Lighthouse audit (Windows PowerShell)
powershell -File scripts/perf-audit.ps1 --mobile
# or desktop:
powershell -File scripts/perf-audit.ps1
# 4. Inspect the HTML report (opens in browser)
start lighthouse-reports/*.report.html
# 5. Analyze client-side bundle sizes
npx cross-env ANALYZE=true next build
# Writes bundle report to reports/bundle-*.html
# 6. Direct webpack-bundle-analyzer against a stats file
npx next build --stats
npx webpack-bundle-analyzer .next/stats.json
# 7. Instrument Core Web Vitals reporting
# - Add to root layout
# - Verify dev console shows [web-vitals] lines
# 8. Measure real-user LCP/CLS/INP
# Endpoint /api/analytics/web-vitals receives beacon batches:
# { name, value, rating, delta, path, navigation_type, dpr, viewport, connection, session, t }
# 9. Verify production build + local audit
npm run build
powershell -File scripts/perf-audit.ps1 --mobile --url http://localhost:3000
```
## 5. Edge Cases & Error Handling
- **Throttling accuracy:** Lighthouse `simulate` mode is an estimate; always verify LCP/CLS against real-user data (`web-vitals` beacons) before shipping. Different CPUs yield dramatical differences under `cpuSlowdownMultiplier`.
- **Chrome path discovery:** If Chrome is not auto-detected, set `LH_CHROME_PATH` explicitly. On serverless CI runners, install a headless shell via `npx puppeteer browsers install chrome-headless-shell`.
- **Bundle analyzer clashes with LRU caches:** Safari prefetches `_next/static` aggressively; the `Cache-Control: immutable` header is mandatory so ICB caching doesn't revalidate on every route change.
- **AVIF fallback:** Older Safari (<16.4) lacks AVIF decode; `next/image` negotiates `accept` headers automatically but only when you pass BOTH `webp` and `avif` in `images.formats`.
- **CLS from async injections:** Reserve stable height for lazy-loaded charts (see the fixed `minHeight: 320` fallback in `LazyChart`). Failing to reserve space causes a CLS spike captured by Lighthouse.
- **Critical CSS inlining size caps:** Inlined `