Firefox Extension Packaging and Distribution Guide

This guide covers the complete process for packaging, signing, and distributing the Anchored Firefox extension.

Prerequisites

  1. Install web-ext CLI tool: 
    cd extension-firefox
npm install
  2. Firefox Add-ons Account:

Building the Extension

Development Build

For testing and development:

npm run build

This creates an unsigned .xpi file in web-ext-artifacts/ directory.

Production Build

For distribution (includes linting):

npm run build:prod

Validation

Validate the extension before submission:

npm run validate

Signing the Extension

Firefox requires all extensions to be signed before they can be installed by users (except in Developer Edition with specific settings).

Option 1: Listed Distribution (Firefox Add-ons Store)

Recommended for public distribution

  1. Set up API credentials (one-time setup): 
    # Windows (CMD)
set WEB_EXT_API_KEY=your_api_key_here
set WEB_EXT_API_SECRET=your_api_secret_here

# Windows (PowerShell)
$env:WEB_EXT_API_KEY="your_api_key_here"
$env:WEB_EXT_API_SECRET="your_api_secret_here"
  2. Sign the extension: 
    npm run sign
  3. Manual review process:

Option 2: Unlisted Distribution (Self-Hosting)

For beta testing or self-distribution

  1. Set up API credentials (same as above)

  2. Sign for unlisted distribution: 
    npm run sign:unlisted
  3. Automatic signing:

Installation and Testing

Installing Unsigned Extension (Development Only)

Firefox Developer Edition or Nightly:

  1. Open about:config
  2. Set xpinstall.signatures.required to false
  3. Open about:debugging#/runtime/this-firefox
  4. Click “Load Temporary Add-on”
  5. Select the .xpi file from web-ext-artifacts/

Installing Signed Extension

Any Firefox version:

  1. Download the signed .xpi file
  2. Open Firefox
  3. Drag and drop the .xpi file into Firefox
  4. Click “Add” when prompted

Testing with web-ext

Run the extension in a temporary Firefox profile:

npm run dev

Run with debugging tools:

npm run test

Update Process

Version Updates

  1. Update version in manifest.json: 
    {
  "version": "1.17"
}
  2. Update version in package.json: 
    {
  "version": "1.17.0"
}
  3. Build and sign: 
    npm run build:prod
npm run sign

Automatic Updates

Firefox automatically checks for updates if:

For unlisted extensions, add to manifest.json:

{
  "browser_specific_settings": {
    "gecko": {
      "id": "anchored@anchored.site",
      "update_url": "https://your-domain.com/updates.json"
    }
  }
}

Distribution Checklist

Before Submission

Store Listing Materials

Reuse from Chrome Web Store with these adjustments:

  1. Extension Name: “Anchored – Notes & Highlights for Websites”
  2. Short Description (250 chars max): 
    Take contextual notes tied to websites. Highlight text and save notes linked to pages you visit. Local-first with optional cloud sync.
  3. Full Description:
  4. Screenshots:
  5. Promotional Images:
  6. Categories:
  7. Support Information:

Submission Process

  1. Go to Firefox Add-ons Developer Hub: https://addons.mozilla.org/developers/

  2. Submit New Add-on:
  3. Review Timeline:

Troubleshooting

Build Errors

Error: Missing manifest.json

# Ensure you're in the extension-firefox directory
cd extension-firefox
npm run build

Error: Invalid manifest

# Validate manifest
npm run lint

Signing Errors

Error: API credentials not found

# Set environment variables
set WEB_EXT_API_KEY=your_key
set WEB_EXT_API_SECRET=your_secret

Error: Signing timeout

# Increase timeout in web-ext-config.js
# Default is 900000ms (15 minutes)

Installation Errors

Error: Extension could not be installed

Error: Extension ID conflict

Security Best Practices

API Credentials

Never commit API credentials to version control:

Code Signing

Privacy

Continuous Integration

GitHub Actions Example

name: Build and Sign Firefox Extension

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: |
          cd extension-firefox
          npm install
      
      - name: Build extension
        run: |
          cd extension-firefox
          npm run build:prod
      
      - name: Sign extension
        env:
          WEB_EXT_API_KEY: $
          WEB_EXT_API_SECRET: $
        run: |
          cd extension-firefox
          npm run sign
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: firefox-extension
          path: extension-firefox/web-ext-artifacts/*.xpi

Resources

Support

For issues with packaging or distribution: