Building Browser Extensions with Manifest V3

Manifest V3 has been the required format for new Chrome Web Store submissions since 2024, and existing V2 extensions have been migrated or removed. Here is a practical guide to building extensions with V3, based on our experience building the AIDToolStack browser extension.

Service Workers Replace Background Pages

The biggest change in V3 is replacing persistent background pages with service workers. Service workers are event-driven and can be terminated by the browser at any time. This means you cannot store state in global variables — use chrome.storage.local for persistent data and chrome.storage.session for ephemeral data. Register all event listeners at the top level of your service worker, not inside callbacks or conditionals.

Content Scripts and Message Passing

Content scripts inject into web pages and can read or modify the DOM. They communicate with the service worker via chrome.runtime.sendMessage. Design your message protocol with explicit action types and structured payloads. Always handle the case where the service worker has been terminated and the response port is disconnected.

The Side Panel API

The Side Panel API is a V3 addition that opens a persistent panel alongside the current tab. It is ideal for tools that users reference while browsing — documentation lookups, AI assistants, or debugging panels. The side panel has full access to Chrome APIs and can communicate with content scripts and the service worker.

Permissions and Security

V3 enforces stricter permissions. Remote code execution is forbidden — all JavaScript must be bundled in the extension. Content Security Policy is tighter by default. Request optional permissions at runtime using chrome.permissions.request rather than declaring broad permissions upfront, which hurts your Chrome Web Store trust score.

Testing and Distribution

Use Playwright or Puppeteer with the --load-extension flag for automated testing. Chrome Web Store review times have improved to 1-3 days for most extensions. For enterprise distribution, use Chrome Enterprise policies to sideload extensions without the store.