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 acceptschrome.*). - Chrome supports
browser.*alongsidechrome.*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": "reading-time@example.com",
"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_permissionsare granted at install, and the user can later restrict them with Site access. - In Firefox, since Firefox 127, MV3 host permissions from
host_permissionsandcontent_scriptsare shown in the install prompt and granted at install. Users can still revoke them at any time fromabout: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:
declarativeNetRequestonly. BlockingwebRequestisn’t available to normal MV3 extensions. - Firefox: supports
declarativeNetRequestand blockingwebRequestin 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 basemanifest.json. - Add small per-browser overrides (for example
manifest.firefox.json) and merge them in a build script. - Output
dist/chrome/anddist/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://extensionsorbrave://extensionswith Developer mode on. - Firefox:
about:debugging#/runtime/this-firefox→ Load Temporary Add-on, orweb-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
browser.*namespace (with a fallback if needed).- Both
service_workerandscriptsinbackground. browser_specific_settings.gecko.idset.- Host permissions checked at runtime, with a grant button.
declarativeNetRequestas the shared filtering layer.- Feature detection for
sidePanel,offscreen, built-in AI and other one-browser APIs. - 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.