How to debug a Firefox add-on (extension)

Before we get started

Firefox supports browser extensions like Chromium-based browsers (Chrome, Arc, Brave, Edge etc.). Sometimes they’re referred to as add-ons in Firefox land.

This post assumes that you are debugging a browser extension you are building, i.e. have the source code for and can build it locally.

It’s also assumed that the Firefox add-on has been built, i.e. generated the files, including a manifest for the add-on to work.

The following instructions work for Firefox and Firefox Deveoper Edition.

Setup Firefox for debugging an add-on

  1. Open the browser DevTools and click on the three dots button, then select settings.

    CleanShot 2023-08-07 at 22 06 39

  2. Scroll down to the Advanced Settings section and ensure Enable browser chrome and add-on debugging toolboxes is checked.

    CleanShot 2023-08-07 at 22 08 32

  3. Load the add-on by clicking on the puzzle icon in the top right of Firefox or via the application menu, Tools -> Add-ons and Themes

    CleanShot 2023-08-07 at 22 11 39

    CleanShot 2023-08-07 at 22 10 35

  4. Click on the cog icon to open the menu and select Debug Add-ons

    CleanShot 2023-08-07 at 22 12 16

  5. Ensure you built the extension with the changes in my branch by running npm run build

  6. Click on the Load Temporary Add-on... button

    CleanShot 2023-08-07 at 22 13 00

  7. Select the manifest file of the add-on from the OS file menu and click the Open button.

    CleanShot 2023-08-07 at 22 14 23

  8. The extension is now ready for use.

    CleanShot 2023-08-07 at 22 15 24

  9. Navigate to a page where you’re using your extension.

  10. If you want to debug or inspect the extension, click the Inspect button from the Temporary Extensions section where the extension was just loaded.

    CleanShot 2023-08-07 at 22 16 54

  11. You now have access to all the same browser dev tools you’re used to for debugging a web site, i.e. Inspect Element, CSS styles inspector, JavaScript debugger, etc.

And that’s it!