Skip to main content
Performance regressions in your extension come from a short list of places. The most common are service worker cold-starts (initial startup delays), heavy content-script injection, oversized UI bundles, and media-heavy web-accessible resources. The checklists below map each type to a concrete fix.

Performance optimization capabilities

Fast optimization pass

  1. Measure first-run behavior on one target browser.
  2. Trim synchronous startup work in content scripts and background handlers.
  3. Defer optional UI features until after initial render.
  4. Re-check build output size and smoke-test critical flows.

Content scripts

  • Keep entry files small and defer non-critical work.
  • Avoid heavy synchronous DOM scans at document_start.
  • Scope observers and event listeners; clean up on remount/dispose.
  • Split reusable logic into shared modules, but avoid fragile dynamic import patterns.

Background/service worker

  • Minimize work at startup; initialize lazily when events arrive.
  • Cache stable computed state where safe.
  • Avoid long-running synchronous tasks in event handlers.
  • Watch service worker dependency churn during active development.

UI surfaces (popup/options/new tab/sidebar)

  • Keep initial render path lightweight.
  • Load large optional UI features on demand.
  • Use framework dev tools only when needed in local debugging sessions.
  • Keep styles modular and avoid large global CSS payloads.

Assets and resources

  • Optimize icon/image sizes by target use.
  • Limit web-accessible resources (WAR) exposure to required assets.
  • Keep public assets intentional; remove stale files.
  • Verify generated dist/<browser> output size regularly.

Trim what ships

Every byte in dist/<browser> is a byte that each user downloads on install and on every update, and a content script’s assets travel with it to every matched page. Here is what extension build already leaves out, where the remaining weight comes from, and where to read the number. What the build excludes. Output starts from manifest.json and follows references. It ships the entries that the manifest names (background, content scripts, pages, icons, locales), the modules and assets that those entries import, and everything under public/. A file in src/ that nothing references is not emitted. A notes file, an unused module, a fixture folder, or a stray image next to your icons never reaches dist/. You do not need an ignore list for them. public/ versus imported assets. The two paths behave differently, and the difference is the usual source of surplus bytes:
  • public/ is copied to the output root as-is, folder structure included, and nothing is checked against it. A stale file there ships. Treat the folder as a list of files that you have decided to ship, and prune it.
  • An asset imported from JavaScript lands at assets/<name>.<hash>.<ext> and ships once, only when the import exists.
  • An asset referenced from an HTML page is written twice: under assets/<relative path> and at its source path, so a reference from script code keeps working. A file referenced from both an HTML page and a JavaScript import ships three times. Import a shared image from JavaScript, or move it to public/ and reference it by root path, so it is written once.
web_accessible_resources scope. On Manifest V3 the build adds two kinds of file to web_accessible_resources, under the union of your content scripts’ matches: every chunk that a content script loads with import(), and every non-script file under assets/, whichever page or script put it there. Files copied from public/ are not added. Two consequences follow. Keep matches as narrow as the feature allows. Keep page-only images out of assets/ (reference them from public/ by root path), so a content script’s matches does not expose them. See Make an extension file readable by a web page. Read the size. extension build prints a tree of the output with the size of each file and closes with the total:
With --zip, a second line names the archive and its compressed size. The archive holds the contents of dist/<browser> and nothing else, under dist/<name>-<version>-<browser>.zip, where the name is the manifest name lowercased with punctuation removed:
For a script, extension build --output json returns total_bytes, largest_asset_bytes, and the size of each entry in zip_artifacts, and the same summary is written to dist/extension-js/<browser>/build-summary.json. Compare total_bytes across commits in CI to catch a size regression before a store review does. See build.

Performance budgets

Production builds (build) emit a warning when a bundle exceeds its per-category size budget. Budgets are enabled in production mode by default, and by default an overrun only warns. Override any category in extension.config.js via perfBudgets (values in bytes):
To fail the build on an overrun, set onExceed: 'error' in perfBudgets. Needs a release after 4.1.41. The overrun is then an error with the code E_PERF_BUDGET, and the build exits 1. Without it, or with onExceed: 'warn', the overrun warns with W_PERF_BUDGET. Any other onExceed value stops the build with E_CONFIG_LOAD. ignore excuses single assets from every budget. List output paths the way the warning prints them, relative to the build folder. In a pattern, * matches inside one folder and ** crosses folders. Budgets layer from weakest to strongest: top-level, then browser.<vendor>, then commands.build. From the release after 4.1.41, a layer that sets one category keeps the categories that another layer set. An ignore list in a stronger layer replaces the weaker list.

What the warning lists

The warning names each file over budget, largest first, with its size, the budget that applied, and its role:
From the release after 4.1.41, the list stops at 20 files. A last line counts the rest, such as and 5 more. A .wasm file can fall under three budgets, so the advice names the one that applied: perfBudgets.runtime, perfBudgets.wasm, or perfBudgets.public. Raise that key when the size is intended, or list the file under ignore.

Invalid budget values

From the release after 4.1.41, a production build refuses an invalid perfBudgets value with the code E_CONFIG_LOAD. Earlier releases dropped or misread such a value without a message. From 4.2.0, dev refuses the same values with E_CONFIG_LOAD before it starts a server. A refused build also marks an earlier ready.json as failed. See ready.json error states. Each refusal names the config file and shows a valid example. The unknown key warning lists the accepted keys: content-script, service-worker, page, shared, public, runtime, wasm, ignore, and onExceed. A budget of 0 does not turn a category off. To stop budgeting a file, list it under ignore. A blank string in ignore is skipped.

Operational checks

  • Run multi-browser build checks in CI.
  • Track regression signals in end-to-end (E2E) runtime duration over time.
  • Add smoke tests for critical extension flows (install, open UI, content script activation).

Common performance pitfalls

  • Large content-script bundles loaded on every matched page
  • Heavy work at document_start without guard conditions
  • Service worker handlers doing synchronous, non-essential initialization
  • UI surfaces shipping large global CSS/JS when you only use partial features

Next steps