Developer

Making One Extension Work in Chrome, Edge and Firefox: A Cross-Browser MV3 Checklist

The practical differences between Chrome, Edge, Brave and Firefox for Manifest V3 extensions as of November 2026: namespaces, backgrounds, IDs, APIs, stores and testing.

Writing an extension once and shipping it to every major browser is more realistic in 2026 than it has ever been. All of them use the WebExtensions model and Manifest V3, and Chrome now supports the standard browser.* namespace. But “mostly compatible” still leaves a handful of differences that cause store rejections and confusing bug reports.

This checklist collects those differences, as of November 2026. It assumes you already have a working Chrome MV3 extension. If not, start with build your first Chrome extension.

1. Pick a namespace strategy

  • Firefox has always provided browser.* with Promise-based APIs (and also accepts chrome.*).
  • Chrome supports browser.* alongside chrome.* since Chrome 148 (Chrome docs). Extensions with a DevTools page got it later, so test those separately.
  • Edge, Brave, Opera, Vivaldi follow Chromium, with timing depending on their Chromium version.

Recommendation: write browser.* if you only support current browsers. If you must support older Chromium versions, add a one-line fallback at the top of each script:

const api = globalThis.browser ?? globalThis.chrome;

All modern extension APIs return Promises in every browser, so async/await works everywhere. Callback-only code is a sign of an outdated example.

2. Background: service worker vs event page

This is the biggest structural difference:

  • Chrome/Chromium requires a service worker: "background": { "service_worker": "background.js" }.
  • Firefox MV3 uses non-persistent event pages: "background": { "scripts": ["background.js"] }.

You can declare both in one manifest. Each browser uses the key it supports and ignores the other:

"background": {
  "service_worker": "background.js",
  "scripts": ["background.js"]
}

Write your background code so it works in both: no DOM APIs (service workers don’t have document or window), register listeners at the top level, and keep state in storage rather than global variables. Our service worker guide covers those patterns.

3. Give Firefox an extension ID

Firefox needs a stable ID for features such as storage sync and native messaging, and for signing. Add:

"browser_specific_settings": {
  "gecko": {
    "id": "[email protected]",
    "strict_min_version": "128.0"
  }
}

Use a domain you control in the ID. Chromium browsers ignore this key. Check MDN’s browser_specific_settings reference for the current requirements, including the data-collection declarations Mozilla has been adding to the manifest.

4. Host permissions behave differently

  • In Chrome, host permissions in host_permissions are granted at install, and the user can later restrict them with Site access.
  • In Firefox, since Firefox 127, MV3 host permissions from host_permissions and content_scripts are shown in the install prompt and granted at install. Users can still revoke them at any time from about:addons, and new host permissions added in an update are not shown to the user (Firefox Extension Workshop).

So in every browser, and especially Firefox, check before relying on page access:

const ok = await browser.permissions.contains({ origins: ['https://example.com/*'] });
if (!ok) showGrantButton(); // call browser.permissions.request() from a click handler

Designing around activeTab and optional permissions from the start makes both browsers happier, and gives users a shorter install warning. See Chrome extension permissions explained.

5. Network filtering

  • Chrome/Edge/Brave: declarativeNetRequest only. Blocking webRequest isn’t available to normal MV3 extensions.
  • Firefox: supports declarativeNetRequest and blocking webRequest in MV3.

Build on declarativeNetRequest as the common base, and add webRequest logic in Firefox only if you need it. Rule limits differ between browsers, so read each browser’s current constants rather than hard-coding Chrome’s. Our declarativeNetRequest by example guide covers the rule format.

6. APIs that exist in only one place

Feature-detect before calling anything outside the common core:

API Chrome Firefox Notes
sidePanel Yes No (sidebar_action instead) Firefox has its own sidebar manifest key
offscreen Yes No Firefox event pages have a DOM, so it’s rarely needed
tabGroups Yes Check MDN for current status Firefox added tab groups to the browser in 2025
Built-in AI (Summarizer, Prompt…) Yes No See Chrome’s built-in AI APIs
userScripts Yes (user must allow) Yes (differs) Behavior and permissions differ
if (browser.sidePanel) {
  await browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
}

The MDN browser compatibility tables are the most reliable single reference.

7. Build one source, several packages

A simple approach that scales:

  • Keep one src/ folder and a base manifest.json.
  • Add small per-browser overrides (for example manifest.firefox.json) and merge them in a build script.
  • Output dist/chrome/ and dist/firefox/, zip each, and submit to the right store.

Tools such as Mozilla’s web-ext help with Firefox linting, running and signing. Run web-ext lint before every Firefox submission. It catches manifest problems that would otherwise come back as review rejections.

8. Test in each browser for real

  • Chrome/Edge/Brave: load unpacked from chrome://extensions, edge://extensions or brave://extensions with Developer mode on.
  • Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on, or web-ext run.

Test the boring paths: first install, update from the previous version, permission denied, browser restart, and the service worker or event page being shut down while idle.

9. Know the stores

Store Fee Notes
Chrome Web Store One-time $5 2-Step Verification required; per-account publishing limit (default two slots for new accounts since August 2026)
Microsoft Edge Add-ons Free Separate review; Edge users can also install from the Chrome Web Store
Firefox Add-ons (AMO) Free Listed or self-distributed; all extensions must be signed by Mozilla

Opera and Brave users can install from the Chrome Web Store, so you rarely need separate listings there. Details on Chrome’s process are in publishing to the Chrome Web Store.

The short checklist

  1. browser.* namespace (with a fallback if needed).
  2. Both service_worker and scripts in background.
  3. browser_specific_settings.gecko.id set.
  4. Host permissions checked at runtime, with a grant button.
  5. declarativeNetRequest as the shared filtering layer.
  6. Feature detection for sidePanel, offscreen, built-in AI and other one-browser APIs.
  7. Separate builds and real-browser tests for each target.

Get these right and most extensions need no browser-specific code beyond a handful of if statements.

Keep reading