web-ext

You can install web-ext either globally on your machine or as a development dependency within a specific project. Ensure you are running a current LTS version of Node.js.

Global Installation

To install the command globally:

npm install --global web-ext

Project-specific Installation

To install as a devDependency (recommended for team version control):

npm install --save-dev web-ext

You can then use it in your package.json scripts. For example, to run an extension from a specific directory:

package.json

"scripts": {
  "start:firefox": "web-ext run --source-dir ./extension-dist/"
}

You can pass additional arguments to npm scripts using the -- suffix, such as specifying a Firefox version:

npm run start:firefox -- --firefox=nightly

To build and install web-ext from the source repository, follow these steps:

1. Uninstall any existing global npm installation:

   npm uninstall --global web-ext

2. Clone the repository and install dependencies:

   git clone https://github.com/mozilla/web-ext.git
   cd web-ext
   npm ci

3. Build the command:

   npm run build

4. Link it to your Node installation:

   npm link

To update, simply pull the latest changes and rebuild:

cd /path/to/web-ext
git pull
npm run build

The web-ext formula is maintained by the community and can be installed using Homebrew:

brew install web-ext

When running the FirefoxAndroidExtensionRunner, it automatically discovers a remote debugging protocol (RDP) Unix socket on the Android device and forwards it to a free local TCP port.

The runner will log the specific TCP port it has chosen. You can use this port to connect Firefox DevTools to the Firefox for Android instance running on your device.

To run an extension on Firefox for Android, use web-ext/util/adb to manage devices and APKs, then call webExt.cmd.run with the firefox-android target.

import webExt from 'web-ext';
import * as adbUtils from "web-ext/util/adb";

// Path to adb binary (optional, auto-detected if missing)
const adbBin = "/path/to/adb";

// Get device and APK info
const deviceIds = await adbUtils.listADBDevices(adbBin);
const adbDevice = ... // select device from deviceIds
const firefoxAPKs = await adbUtils.listADBFirefoxAPKs(adbDevice, adbBin);
const firefoxApk = ... // select APK from firefoxAPKs

webExt.cmd.run({
  target: 'firefox-android',
  firefoxApk,
  adbDevice,
  sourceDir: ...
}).then((extensionRunner) => {
  // Handle extension runner
});

Use webExt.cmd.sign() to request a signed .xpi from Mozilla. This is the recommended method over using the internal submit-addon module.

import webExt from 'web-ext';

webExt.cmd.sign({
  // Set userAgentString to a custom one of your choice
  userAgentString: 'YOUR-CUSTOM-USERAGENT',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  amoBaseUrl: 'https://addons.mozilla.org/api/v5/',
  sourceDir: '...',
  channel: 'unlisted',
});

Since version 7.0.0, the web-ext npm package exports NodeJS native ES modules only. If you are using CommonJS, you must use dynamic imports.

Use webExt.cmd.run() to execute commands programmatically. Note that web-ext is primarily a CLI tool, and its internal API has limited support and may change in minor/patch updates.

Example of running an extension:

import webExt from 'web-ext';

webExt.cmd
  .run(
    {
      // Command options (e.g., --source-dir becomes sourceDir)
      firefox: '/path/to/Firefox-executable',
      sourceDir: '/path/to/your/extension/source/',
    },
    {
      // Non-CLI related options
      // Set shouldExitProgram to false to keep your Node app running
      shouldExitProgram: false,
    },
  )
  .then((extensionRunner) => {
    console.log(extensionRunner);
    // extensionRunner.reloadAllExtensions();
    // extensionRunner.exit();
  });

You can control the behavior of the web-ext execution via the options object in the second argument of webExt.cmd.run().

Verbose Logging

Use web-ext/util/logger to enable verbose logging:

import * as webExtLogger from 'web-ext/util/logger';

webExtLogger.consoleStream.makeVerbose();
webExt.cmd.run({ sourceDir: './src' }, { shouldExitProgram: false });

Disable Standard Input

To prevent web-ext from using standard input, pass noInput: true in the command options:

webExt.cmd.run({ sourceDir: './src', noInput: true }, { shouldExitProgram: false });

The web-ext CLI provides several core commands for extension development. You can view detailed documentation for any command by appending --help (e.g., web-ext build --help).

• run: Run the extension.
• lint: Validate the extension source.
• sign: Sign the extension so it can be installed in Firefox.
• build: Create an extension package from source.
• docs: Open the web-ext documentation in a browser.

When using FirefoxDesktopExtensionRunner, you can reload extensions without restarting the browser instance.

• To reload all extensions: Call await runner.reloadAllExtensions(). This returns an array of results. If multiple extensions fail to reload, it returns a MultiExtensionsReloadError containing a map of errors keyed by sourceDir.
• To reload a specific extension: Call await runner.reloadExtensionBySourceDir(extensionSourceDir). This requires the extensionSourceDir used during the initial setup. If the extension is not found or cannot be reloaded, it returns a WebExtError.