MDN’s new design is in Beta! A sneak peek:

Developing WebExtensions for Firefox for Android

You will approach the coding of a WebExtension for Firefox for Android in the same way as you would for a desktop WebExtension; using a text editor or tool of your choice to write the code. However, when you get to testing and debugging your WebExtension you need to follow a different process, this article walks you through that process.

Set up your computer and Android emulator or device

You first need to complete some one-off setup tasks on your computer and Android device.

On your development computer:

  • If you want to test on your computer by running Firefox for Android in the Android emulator:
  • If you plan to test in Firefox for Android running on a device only:
    • Download and extract the standalone Android SDK Platform-Tools package to a suitable location on your computer.
    • On Windows, Mac, or Linux: Add the location into which you extracted the tools package to your operating system’s PATH environment variable.
    • Alternatively, on Mac or Linux: Link the binary to /usr/local/bin using sudo ln -s /<extract folder>/platform-tools/adb /usr/local/bin.

On your device or Android emulator:

If you are using a device:

On your development computer:

  • Open a command shell.
  • Run adb devices
    You should see output similar to:
    List of devices attached
    51800F220F01564 device

    Where the hex string is your device’s (or emulator’s) code. This means adb has found your device (or emulator).

Install and run your add-on in Firefox for Android

In your WebExtension ensure that you have included an application ID using the applications key in the manifest.json:

 "applications": {
    "gecko": {
       "id": ""

Zip the content of your add-on into an xpi file named to match the application ID, for example,

You now have two options for transferring and running your addon: using adb or a website.

Transfer your add-on using adb

On your computer, execute /path/to/adb push /path/to/<add-on file name>.xpi /mnt/sdcard/, which will transfer the WebExtensions xpi file to your attached emulator or device.

On your Android device or in the emulator, open Firefox for Android and browse to file:///mnt/sdcard:

Firefox for Android showing the add-on xpi file located on the memory card

Tap on <add-on file name>.xpi to install it. You will get a warning about the add-on being blocked, tap ALLOW:

Firefox for Android blocked add-on message

An additional warning will tell you the add-on is unverified, tap INSTALL:

Firefox for Android unverified add-on message

Your add-on will start running (in this case a copy of the borderify example WebExtension):

Borderify shown adding a red border to the home page

Transfer your add-on via a website.

Upload your xpi file to your website and make it accessible over HTTP. Browse to the file and download it. Follow the installation instructions, which will be similar to those for an add-on transferred using adb.

Debug your add-on

You can debug your add-on in WebIDE and view any manifest,json validation messages using adb logcat. To make use of these features, first set up Firefox remote debugging over USB or Wi-Fi.

Using WebIDE to debug your add-on

Open WebIDE from the Developer option on the desktop Firefox menu. Once open, select your connected device from the options in the right-hand sidebar.

Selecting the Firefox for Android device from the list in WebIDE

Now, ensure you are viewing the Main Process, then load a page in which your add-on will be exercised.

Unlike desktop Firefox, where background scripts output their console messages and are debugged in the add-on debugger, while content scripts output their console messages and are debugged in the browser’s developer tools (see Debugging content scripts), you can view all messages and debug all scripts in WebIDE when running add-ons in Firefox for Android.

If you included any console messages in your add-on (using console.log()), you can see these the Console tab, and can use the console filter (highlighted below) to hide other console messages:

WebIDE showing console with messages filtered for those including 'borderify'

The Debugger tab then enables you to access the background script and any content scripts:

The borderify.js script in the WebIDE debugger tab

You can now apply breakpoints and observe the add-on’s behavior.

Also, you can also target the document related to an extension page, for example, the background page of the borderify example, using the same approach described for the Browser Toolbox:

Selecting a specific page to examine in the WebIDE

Once you have switched to an extension page, you can inspect the extension page’s DOM elements from the Inspector panel (also the "inspect node" toggle button should work as expected) and execute WebExtension API calls from the Console panel:

Using the interactive console to test the effect of JavaScript on the open page

For more details on using WebIDE, see the WebIDE section.

Viewing manifest validation messages using the console

In addition to the console messages output through WebIDE, there may also be messages relating to the validation of the add-on’s manifest.json files. These messages can be viewed using the adb logcat command. To avoid receiving other, unrelated messages, you can pipe the output through grep, filtering by the add-on’s ID, for example:

/path/to/adb logcat | grep

This will give output similar to this:

I/Gecko   (30440): 1496056181889    addons.xpi    WARN    Addon with ID already installed, older version will be disabled

If your add-on fails to run, check these messages as they may provide information explaining why.

Document Tags and Contributors

 Contributors to this page: rebloor
 Last updated by: rebloor,