firefox-scaffold

Firefox Extension Scaffold

Scaffold a production-ready Firefox WebExtension with Manifest V3 defaults, web-ext CLI integration, and AMO-compatible structure.

CRITICAL RULES

1. Default to Manifest V3. Firefox MV3 supports both background.scripts (event pages with DOM access, unlike Chrome) and declarativeNetRequest. Only use V2 when the user has an explicit reason (ESR Firefox target, specific APIs not in V3).
2. Generate a working "Hello World" the user can load immediately via web-ext run. No TODO placeholders as the only content of any file.
3. Match AMO submission requirements from day one: no binary blobs without source, no obfuscated code, valid semver, unique id in browser_specific_settings.
4. Never hardcode user identity. If the user does not specify --author or --id, prompt them.

Procedure

1. Parse arguments

• extension-name: required, kebab-case (becomes directory name + manifest name slugified)
• --mv V2 | V3: manifest version (default V3)
• --sidebar: include sidebar_action
• --content-script: include content script template (default: include)
• --options-page: include options UI template

If extension id not provided, ask the user for their preferred format ({extension-name}@example.com or email-style) -- AMO requires a unique ID.

2. Directory layout

<extension-name>/
  manifest.json
  src/
    background.js            (or background.ts if --ts)
    content.js               (if --content-script)
    popup/
      index.html
      popup.js
      popup.css
    options/                 (if --options-page)
      index.html
      options.js
    sidebar/                 (if --sidebar)
      index.html
      sidebar.js
  icons/
    icon-48.png
    icon-96.png
  web-ext-config.js
  .web-ext-artifacts/        (gitignored, build output)
  .gitignore
  package.json
  README.md

3. Write manifest.json (MV3)

{
  "manifest_version": 3,
  "name": "{{Extension Name}}",
  "version": "0.1.0",
  "description": "{{One-line description}}",
  "author": "{{Author from prompt}}",
  "icons": {
    "48": "icons/icon-48.png",
    "96": "icons/icon-96.png"
  },
  "browser_specific_settings": {
    "gecko": {
      "id": "{{extension-id from prompt}}",
      "strict_min_version": "128.0"
    }
  },
  "permissions": [],
  "host_permissions": [],
  "background": {
    "scripts": ["src/background.js"]
  },
  "action": {
    "default_popup": "src/popup/index.html",
    "default_title": "{{Extension Name}}"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["src/content.js"]
    }
  ]
}