Browser Extensions Firefox Extension Dev

Firefox Extension Development Expert

Build, debug, publish, and maintain Firefox WebExtensions. Covers Manifest V2 and V3, all 51 browser.* APIs, cross-browser compatibility, AMO publishing, and Firefox-specific features. Actively writes code, scaffolds projects, and fetches live documentation from MDN.

When to Use

Trigger on: Firefox extension, WebExtension, browser add-on, manifest.json for extensions, content scripts, background scripts, browser.tabs, browser.storage, AMO publishing, web-ext CLI, Manifest V3 migration, cross-browser extension, sidebar extension, native messaging extension.

Documentation Lookup Strategy

Knowledge sourced from MDN WebExtensions docs + live search for details not covered in reference files.

Lookup priority

1. Check reference files first - references/browser-api-reference.md, references/manifest-schema.md, references/amo-publishing.md, references/mdn-api-urls.md
2. WebFetch MDN page - if the reference files lack detail on a specific method, event, or parameter, fetch the MDN page directly. URL pattern: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/<APIName>/<method>. See references/mdn-api-urls.md for the full URL index.
3. WebSearch as fallback - when the exact URL is unknown or for newer/experimental APIs, search with: site:developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions <query>
4. Extension Workshop - for publishing, review policies, migration guides: site:extensionworkshop.com <query>

When to search

• User asks about a specific API method/event not detailed in reference files
• User asks about browser compatibility for a specific feature
• User asks about experimental or recently added APIs
• User references an error message or unexpected behavior
• User needs examples beyond what reference files provide

Key resources

• MDN docs source: mdn/content
• Official examples: mdn/webextensions-examples
• Browser API polyfill: mozilla/webextension-polyfill
• web-ext CLI: mozilla/web-ext
• Extension Workshop: extensionworkshop.com

Operational Modes

Scaffolding a New Extension

When the user wants to create a new extension:

1. Ask: MV2 or MV3? (default MV3)
2. Ask: what does the extension do? (content script, popup, sidebar, DevTools, background-only)
3. Generate project structure based on answers:

Minimal MV3 scaffold:

my-extension/
  manifest.json          # MV3, gecko ID, permissions
  background.js          # event page with onInstalled listener
  icons/
    icon-48.png          # placeholder note
    icon-96.png

With popup:

+ popup/
    popup.html
    popup.js
    popup.css

With content script:

+ content-scripts/
    content.js
    styles.css

With sidebar (Firefox-only):

+ sidebar/
    sidebar.html
    sidebar.js

With options page:

+ options/
    options.html
    options.js

With i18n:

+ _locales/
    en/messages.json

4. Generate manifest.json with correct keys for chosen components
5. Generate starter code with common patterns (message passing, storage, event listeners)
6. Include a .web-extension-id file reminder for AMO

Writing Extension Code

When implementing features:

• Always use browser.* namespace (not chrome.*) - Firefox-first
• Always use Promises/async-await (not callbacks)
• Register all event listeners at top level in background scripts (MV3 requirement)
• Use storage.local/storage.session for state (not globals, not localStorage)
• Use browser.alarms for periodic tasks (not setTimeout/setInterval in MV3)
• Sanitize any user/page input before DOM insertion
• Use activeTab permission when possible instead of broad host permissions
• Include error handling for all API calls (try/catch or .catch())

Debugging Assistance

When the user reports a bug or unexpected behavior:

1. Check manifest.json for permission/key issues
2. Check content script match patterns
3. Check MV3 event page rules (top-level listener registration, state persistence)
4. Suggest web-ext lint for common issues
5. Point to relevant debugging tools (about:debugging, Browser Console, Extension Debugger)
6. If the issue involves a specific API, fetch the MDN page for current behavior/compatibility

Extension Anatomy

Every extension is a collection of files packaged as a .zip. The only mandatory file is manifest.json.

File Structure

my-extension/
  manifest.json              # REQUIRED - metadata + pointers
  background.js              # event handling, extension lifecycle
  content-scripts/
    content.js               # injected into web pages
    styles.css               # injected styles
  popup/
    popup.html               # toolbar button popup
    popup.js
    popup.css
  sidebar/
    sidebar.html             # sidebar panel (Firefox-only)
    sidebar.js
  options/
    options.html             # settings page
    options.js
  icons/
    icon-48.png
    icon-96.png
  _locales/                  # i18n strings
    en/messages.json
  web-accessible-resources/  # files accessible to page scripts

Component Types

Content Scripts

Loading Methods

1. Declarative (manifest.json):

{
  "content_scripts": [{
    "matches": ["*://*.example.com/*"],
    "exclude_matches": ["*://admin.example.com/*"],
    "js": ["jquery.js", "content.js"],
    "css": ["styles.css"],
    "run_at": "document_idle",
    "all_frames": false,
    "match_about_blank": false
  }]
}

run_at values:

• document_start - before DOM construction
• document_end - DOM ready, before subresources
• document_idle - default, after page load

2. Programmatic (MV3 scripting API):

await browser.scripting.executeScript({ target: { tabId }, files: ["content.js"] });
await browser.scripting.insertCSS({ target: { tabId }, files: ["styles.css"] });
await browser.scripting.registerContentScripts([{
  id: "my-script", matches: ["*://*.example.com/*"],
  js: ["content.js"], persistAcrossSessions: true
}]);

Content Script Environment

• DOM access: Full access to page DOM via standard Web APIs
• JS isolation: Cannot see page-defined JS variables (Xray vision in Firefox)
• API access: Limited subset - runtime, i18n, storage, extension, menus.getTargetElement

Background Scripts

MV3 Event Page (Firefox)

Firefox MV3 uses event pages (non-persistent background pages with DOM access), NOT service workers like Chrome.

Critical rules for event pages:

1. Register listeners at top level synchronously - deferred registration breaks wake-up
2. Persist state via storage.session/storage.local, not globals
3. Use browser.alarms instead of setTimeout/setInterval
4. runtime.onSuspend fires before unload - use for cleanup

Message Passing

One-Off Messages

// Content script -> Background
browser.runtime.sendMessage({ type: "getData", key: "user" }).then(response => console.log(response));

// Background -> Content script
await browser.tabs.sendMessage(tabId, { type: "update", data: newData });

Port Connections (Long-Lived)

const port = browser.runtime.connect({ name: "data-stream" });
port.postMessage({ greeting: "hello" });
port.onMessage.addListener((msg) => { /* handle */ });

Content Script to Page Script (window.postMessage)

Security warning: Never eval() data received from page scripts. Extensions are privileged code - hostile pages can exploit this.

Match Patterns

Syntax: <scheme>://<host><path>

Permissions

Install-Time vs Optional

• permissions + host_permissions (MV3) granted at install
• optional_permissions + optional_host_permissions requested at runtime from user action handler
• Users can revoke optional permissions in Add-ons Manager (since Firefox 84)

Native Messaging

Enables communication between extension and native applications.

• Permission: nativeMessaging
• Native app manifest: JSON with name, path, type: "stdio", allowed_extensions
• Wire protocol: JSON UTF-8, 32-bit unsigned length prefix
• Limits: Max 1 MB from app, max 4 GB to app
• Use runtime.connectNative() for connection-based or runtime.sendNativeMessage() for one-off

Firefox-Specific Features

Manifest V3 Migration

Firefox MV3 vs Chrome MV3

Migration Checklist (MV2 to MV3)

1. Set "manifest_version": 3
2. Move host permissions from permissions to host_permissions / optional_host_permissions
3. Rename browser_action to action, _execute_browser_action to _execute_action
4. Remove browser_style from all manifest keys
5. Replace tabs.executeScript/insertCSS/removeCSS with browser.scripting API
6. Convert background to non-persistent
7. Move all event listeners to top-level synchronous registration
8. Replace global state variables with storage.session/storage.local
9. Replace setTimeout/setInterval with browser.alarms
10. Update CSP format: "content_security_policy": { "extension_pages": "..." }
11. Update web_accessible_resources to object array format
12. Remove all eval() usage (forbidden in MV3)

Cross-Browser Compatibility

Namespace

• Firefox: browser.* (Promises) + chrome.* (callbacks)
• Chrome: chrome.* (MV2: callbacks, MV3: Promises from Chrome 121+)
• Safari: browser.* (Promises)

Strategy

1. Code for Firefox first using browser.* + Promises
2. Apply webextension-polyfill for Chrome/Edge/Opera
3. Use runtime feature detection for platform-specific APIs
4. Create separate manifest.json per browser

Development Workflow

web-ext CLI

web-ext run --firefox nightly --browser-console --start-url https://example.com
web-ext lint
web-ext build --overwrite-dest
web-ext sign --channel unlisted --api-key $WEB_EXT_API_KEY --api-secret $WEB_EXT_API_SECRET

Loading Temporarily

1. Open Firefox - about:debugging#/runtime/this-firefox
2. Click "Load Temporary Add-on..."
3. Select manifest.json from extension directory

Debugging

• Browser Console: Ctrl+Shift+J - background script logs
• Extension Debugger: about:debugging - Inspect on extension
• Content Script Console: Regular page DevTools (select extension context)

Common Patterns

• Toolbar button with popup: action manifest key + popup HTML/JS
• Context menu: browser.menus.create() + menus.onClicked
• Page modification: Content script with DOM manipulation
• Options page: options_ui manifest key + storage sync
• Web request interception: webRequest.onBeforeRequest with blocking
• Badge text: browser.action.setBadgeText() + setBadgeBackgroundColor()
• Periodic tasks (MV3): browser.alarms.create() + alarms.onAlarm

Debugging Checklist

1. Check about:debugging - is the extension loaded? Any errors?
2. Browser Console (Ctrl+Shift+J) - background script errors
3. Page DevTools Console - content script errors (select extension context)
4. Permissions - are all needed permissions declared?
5. Match patterns - do content script patterns match the target URLs?
6. CSP violations - check for Content Security Policy blocks
7. MV3 event page - are listeners registered synchronously at top level?
8. Storage - using browser.storage instead of window.localStorage?
9. Run web-ext lint to catch common issues

References

• references/browser-api-reference.md - Complete list of all 51 browser.* APIs with methods, events, and permissions
• references/manifest-schema.md - Full manifest.json key reference with MV2/MV3 examples
• references/amo-publishing.md - AMO publishing checklist, review policies, CSP, security best practices, i18n
• references/mdn-api-urls.md - Direct MDN URL index for all browser.* APIs, manifest keys, and Extension Workshop resources
• references/best-practices.md - Best practices, pitfalls, and anti-patterns: JS patterns, Workers, sessions, startup, security, performance, cross-browser