Extension performance playbook

​

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.

​

Performance budgets

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.
• Review Security checklist.