Lwc Performance Budgets

LWC Performance Budgets

Budget Enforcement Triggers

• Shipping any LWC rendered above-the-fold on a high-traffic record page or Experience Cloud route.
• A component has a history of bloating over releases.
• CrUX field data shows LCP or INP regressing post-release and you want a preventive gate.

When NOT To Use

• Internal-only admin utility components (still valuable but lower-priority).
• Components built into a managed package where you cannot change CI.

Budget What You Can Actually Measure

Half the work here is deleting rows that look right and can never fail. Two metrics that appear in almost every generated budget do not exist in a Salesforce context:

• Minified bundle size. The platform compiles and serves LWC. sf project deploy sends source; there is no local build emitting a minified artefact to weigh. Budget source bytes plus transitive import bytes instead — both are stdlib-checkable in CI and stable across releases.
• CrUX field data for an internal org. The Chrome UX Report covers public origins. An authenticated Lightning org is not in it. Public Experience Cloud sites are the exception where CrUX genuinely applies.

The Five Budget Types

1. Source + transitive bytes. Per bundle, including everything reachable through from 'c/moduleName'. Measuring only the leaf file misses the 2 KB component that imports 60 KB of shared utilities — the common case. Exclude @salesforce/* and lightning/*; they are platform-provided.
2. Round trips. @wire count is a cheap static check (≤ 3 on a top-level component). Calls-per-user-action needs a Jest assertion with mocked Apex and advanced timers — that is what catches a removed debounce; a decorator count never will.
3. Rendered volume. The published datatable guidance is 1,000 rows and 5 columns, fewer than 20 columns past 250 rows, and 50 rows per request. Make those manifest rows.
4. Client-side collection size. Lightning Web Security mediates cross-namespace access with proxies; the cost is "negligible when there are a few thousand proxies" and "observable" in the tens of thousands. Set a ceiling and enforce it as a guard that throws rather than degrades.
5. Core Web Vitals — LCP, INP, CLS — as a field alert on public sites and a lab pre-release check elsewhere. Label every number lab_ or field_ and never compare them; they are different quantities.

Recommended Workflow

1. Inventory components and the pages hosting them, and record whether each page is one you fully control (LWR site, custom app page) or platform-composed. On platform-composed pages, budget the component-attributable delta, not the page total — most of that timeline is not yours.
2. Measure the current distribution first. Set initial defaults near the observed 75th percentile so the outliers are the failures. A default that forty components violate on day one gets the gate disabled, and disabled gates do not come back.
3. Write the manifest with an owning team on every entry, an explicit gate (ci-blocking / monitor-alert / manual-pre-release / warn-only), and a stated measurement method per row. A row with no gate is documentation — say so.
4. Wire CI to report every violation before exiting non-zero. Fail-fast turns one bad PR into five build cycles and pushes people to run the check in a local loop instead of reading the manifest.
5. Add expiring waivers with an id, reason, approver, and expiry — plus a check that fails the build on an expired waiver. Without it "expires" is decorative and every waiver is a permanent, unapproved budget increase.
6. Write the regression playbook in this order: is it us (compare a page with none of your components), then did data volume grow, then did code change. The first two are cheap and are usually where the answer is.
7. Put reviewed and next_review in the manifest with a check that warns once the date passes, and a completeness check warning on any bundle with no entry. Ratchet quarterly toward the observed 90th percentile.

Official Sources Used

• Improve Performance (LWC Developer Guide) — https://developer.salesforce.com/docs/platform/lwc/guide/perf-intro.html
• Best Practices for Development with Lightning Web Components — https://developer.salesforce.com/docs/platform/lwc/guide/get-started-best-practices.html
• Improve Datatable Performance — https://developer.salesforce.com/docs/platform/lwc/guide/data-table-performance.html
• How LWS Architecture Affects Component Performance — https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-performance.html
• Core Web Vitals — https://web.dev/vitals/
• Lighthouse CI — https://github.com/GoogleChrome/lighthouse-ci