> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension performance playbook

> Keep extension startup fast and runtime overhead low across content scripts, service workers, and UI surfaces. Prevent common performance regressions.

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

| Area            | What this helps you optimize                                          |
| --------------- | --------------------------------------------------------------------- |
| Content scripts | Injection cost, DOM work timing, and remount overhead                 |
| Service worker  | Startup path, event handling cost, and cold-start behavior            |
| UI surfaces     | Initial render size and optional feature loading                      |
| Assets          | Bundle size, icon/media weight, and web-accessible resource footprint |
| Operations      | Continuous integration (CI) checks and runtime regression tracking    |

## 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.

## Performance budgets

Production builds (`build`) emit a **warning** when a bundle exceeds its per-category size budget. Budgets are warn-only — they never fail the build — and are enabled in production mode by default.

| Category                                                | Default budget | Why                                                        |
| ------------------------------------------------------- | -------------- | ---------------------------------------------------------- |
| Content scripts                                         | 512 KiB        | Injected on every matched page navigation.                 |
| Service worker                                          | 512 KiB        | Wakes from cold on each event; large bundles slow startup. |
| Pages / UI (popup, options, sidebar, devtools, new tab) | 1 MiB          | Opened on demand.                                          |

Override any category in [`extension.config.js`](/docs/features/extension-configuration) via `perfBudgets` (values in bytes):

```js theme={null}
export default {
  perfBudgets: {
    "content-script": 768 * 1024,
    "service-worker": 512 * 1024,
    page: 2 * 1024 * 1024,
  },
};
```

## 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

* Review [Playwright E2E](/docs/workflows/playwright-e2e).
* Review [Security checklist](/docs/workflows/security-checklist).