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.

  1. Record the page, build, device profile, and test conditions.
  2. Compare lab diagnostics with field distributions and user reports.
  3. Find the largest verified bottleneck before selecting a fix.
  4. 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.

json
[{"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.

json
{
  "ci": {
    "collect": { "url": ["http://localhost:3000/"] },
    "assert": { "budgetsFile": "./budget.json" }
  }
}
yaml
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: true

Action 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?