Building A Firefox Extension

1 year ago firefox

While browser extensions exist for nearly every purpose, sometimes you need a custom solution tailored to your specific needs. Learning to build your own browser extension can transform the way you work, empowering you to create tools that streamline your workflow and open up a world of new possibilities.

Remember to keep it simple. Extensions can be overkill and a simple userscript might get the same job done. For userscripts checkout Violentmonkey.

The Project Structure

The Manifest file

In the manifest, you'll define key details about your extension, including its name, description, version, icons, permissions, and more. Importantly, the manifest also specifies the paths to your script files

{
    "manifest_version": 2,
    "name": "Foobar",
    "description": "This is a foobar extension that does things",
    "version": "1.0.0",
    "icons": {
        "64": "icons/main.png"
    },
    "permissions": [
        "tabs",
        "contextMenus",
        "http://*/*",
        "https://*/*",
        "storage"
    ],
    "content_security_policy": "script-src 'self'; object-src 'self'",
    "background": {
        "scripts": [
            "background_script.js"
        ]
    },
    "options_ui": {
        "page": "settings/options.html"
    },
    "browser_specific_settings": {
        "gecko": {
            "id": "2d4a2d4a-2d4a-2d4a-2d4a-2d4a2d4a2d4a"
        }
    },
    "content_scripts": [
        {
            "matches": [
                "<all_urls>"
            ],
            "js": [
                "content_script.js"
            ]
        }
    ],
    "browser_action": {
        "default_icon": {
            "64": "icons/main.png"
        },
        "default_popup": "popup/index.html",
        "browser_style": true
    }
}

Script files

Background script

The background script runs persistently in the background of the browser, with access to the browser API. It’s ideal for tasks like creating a context menu or listening to events. If you need something to run at intervals, say every 15 minutes, this is where to set it up.

Content script

The content script runs on the specific webpage you're viewing, giving you access to the page’s DOM. Use it to read or modify content on the page. Want to add extra buttons or alter the layout? This is the place to make those changes.

The popup script activates when you click on the extension icon. This opens a popup window where you can add interactive elements, like buttons to toggle the extension on or off or any other controls you might need.

Options script

The options script runs when you click the options button in the extension settings. It allows you to build a settings page for your extension, providing users with customizable options.

Essential Tool: Web-ext

For extension development, I highly recommend using web-ext. This tool lets you test your extension in a sandboxed Firefox instance, automatically reloading it as you make code changes. When you're ready to publish, web-ext can also package your extension into a ZIP file, making the whole process smoother and faster.

# This will run the extension in a sandboxed Firefox instance,
# and it will also reload the extension when you make changes to the code.
web-ext run
# This will build the extension for you into a zip file. Make sure to bump
# the version number in the manifest file before building.
web-ext build

Debugging

When debugging, you’ll need to check different consoles depending on which script is running.

Content Script: To debug a content script, open the page's developer tools as usual (hotkey: Ctrl+Shift+I). The console here will show logs and errors specific to content scripts running on the page.

Background Script: Debugging a background script requires accessing the console through the extensions page:

  1. Go to the extensions page (hotkey: Ctrl+Shift+A).
  2. Click the cog icon and select "Debug Add-ons." debug add-ons
  3. Find your extension and click "Inspect." inspect add-ons

Getting it into Production

Once you’ve built your extension, it can only run in a development version of Firefox with unsigned extensions enabled.

To make it work in standard Firefox, you’ll need to get it signed by Mozilla:

  1. Create an account on the Firefox Add-ons site.
  2. Submit your ZIP file of the extension for review.

Once approved and signed, the extension can be installed on any Firefox instance.

Other Posts