Firefox Addon Project Structure

WebExtension-based Firefox addon with background script, content scripts, and browser action popup.

#firefox #addon #webextension #browser #javascript

PNG PDF

Project Directory

my-addon/

manifest.json

WebExtension manifest

src/

Source code

background/

Background scripts

background.js

Persistent background

messages.js

Message handlers

content/

Content scripts

content.js

Injected into pages

content.css

popup/

Browser action popup

popup.html

popup.js

popup.css

options/

Addon preferences page

options.html

options.js

options.css

lib/

Shared utilities

storage.js

browser.storage wrapper

api.js

assets/

Static resources

icons/

icon-48.png

icon-96.png

_locales/

i18n translations

en/

messages.json

package.json

web-ext-config.js

web-ext CLI config

.gitignore

README.md

Why This Structure?

This structure uses the WebExtensions API which is largely compatible with Chrome extensions. Firefox supports persistent background scripts (unlike Chrome's Manifest V3 service workers), giving you more flexibility for long-running operations.

Key Directories

src/background/-Persistent background script with full API access
src/content/-Scripts injected into web pages
src/popup/-Browser action popup UI
src/options/-Addon preferences page

Manifest Structure

// manifest.json
{
  "manifest_version": 2,
  "name": "__MSG_extensionName__",
  "version": "1.0.0",
  "browser_action": {
    "default_popup": "src/popup/popup.html",
    "default_icon": { "48": "assets/icons/icon-48.png" }
  },
  "background": {
    "scripts": ["src/background/background.js"]
  },
  "permissions": ["storage", "activeTab"],
  "browser_specific_settings": {
    "gecko": { "id": "[email protected]" }
  }
}

Getting Started

npm install -g web-ext
Create manifest.json with browser_specific_settings.gecko.id
Add icons in assets/icons/ (48, 96px)
web-ext run to launch Firefox with addon loaded
web-ext build to create distributable .zip

Firefox-Specific Features

browser.*-Promise-based APIs (vs Chrome's callbacks)
Persistent background-No service worker limits like Manifest V3
Sidebar support-Native sidebar_action API
Container tabs-contextualIdentities API for tab isolation

Best Practices

Use browser.* APIs with promises, not chrome.* callbacks
Include browser_specific_settings.gecko.id in manifest
Use web-ext lint to validate before submission
Test in Firefox Developer Edition
Support both Manifest V2 and V3 if targeting multiple browsers

Cross-Browser Tips

For cross-browser compatibility, use the webextension-polyfill library which provides the Promise-based browser.* API for Chrome. Structure code to work with both browsers from a single codebase.

When To Use This

Firefox-specific features (containers, sidebar)
Need persistent background scripts
Privacy-focused extensions
Cross-browser extension development
Developer tools and debugging utilities

Trade-offs

Manifest V2-Still supported but V3 coming; plan for migration
Smaller market-Firefox has smaller user base than Chrome
Review process-AMO review can take longer than Chrome Web Store