Engineering guide
Web Performance Optimization
Use a baseline, choose a change tied to a measured bottleneck, then recheck the same journey on representative devices and networks.
Start with evidence
Lab results from Lighthouse are repeatable diagnostics in a controlled run. Field data such as CrUX reflects real users across devices and conditions. A budget is a project guardrail or estimate, not a promise that a particular score or field result will follow.
- Record the page, build, device profile, and test conditions.
- Compare lab diagnostics with field distributions and user reports.
- Find the largest verified bottleneck before selecting a fix.
- Repeat the same measurement after the change and watch regressions.
One page, three vital checks
LCP · 2.8s
Symptom: The hero image is the largest visible element and arrives late.
Measure: Inspect its request priority and transfer size in a mobile lab trace.
Fix: Serve a correctly sized responsive image; preload only if discovery is late.
Recheck: Re-run the same route and viewport; confirm the hero request and LCP timestamp improve.
INP · 310ms
Symptom: Opening the filter menu has a long interaction delay.
Measure: Use a performance trace to locate long main-thread tasks during that interaction.
Fix: Reduce synchronous work, split non-critical JavaScript, and avoid needless rerenders.
Recheck: Repeat the interaction with the same data and device profile; inspect responsiveness.
CLS · 0.16
Symptom: A late-loaded banner shifts the article down.
Measure: Use layout shift attribution to identify the element and session window.
Fix: Reserve the banner dimensions and provide image width/height attributes.
Recheck: Reload under the same network conditions and confirm the layout remains stable.
For image delivery, use responsive srcset/sizes, modern formats where supported, and avoid lazy-loading the likely LCP image. For fonts, subset and serve only needed weights; use `font-display` thoughtfully. Third-party scripts compete for network and main-thread time, so remove or defer those that are not needed for the initial experience.
Set a measurable CI guardrail
Budget limits should match the page’s priorities and be reviewed with each release. The sample uses Lighthouse CI assertions against the same resource-size budget structure exported by UIWorkbench’s Web Performance Budget tool. The categories include document, stylesheet, script, image, font, third-party, and total resource size.
[{"resourceSizes":[
{"resourceType":"document","budget":50},
{"resourceType":"stylesheet","budget":40},
{"resourceType":"script","budget":120},
{"resourceType":"image","budget":180},
{"resourceType":"font","budget":50},
{"resourceType":"third-party","budget":40},
{"resourceType":"total","budget":480}
]}]Configure Lighthouse CI to read the budget file, then make the audit job required in repository branch protection when the team is ready to enforce it.
{
"ci": {
"collect": { "url": ["http://localhost:3000/"] },
"assert": { "budgetsFile": "./budget.json" }
}
}name: Lighthouse budget
on: [pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: treosh/lighthouse-ci-action@v12
with:
configPath: .lighthouserc.json
uploadArtifacts: trueAction versions and configuration can change; check the current Lighthouse CI configuration reference before adopting the workflow.
Report review checklist
- Is this a representative route, build, device, and network?
- Are lab and field measurements clearly separated?
- Does the trace identify the suspected cause?
- Does the fix improve the same measurement without creating regressions?
- Are budgets tied to user value and maintained as the product changes?