Repository files navigation

This is a command line tool to help build, run, and testWebExtensions.

Ultimately, it aims to support browser extensions in a standard, portable,cross-platform way. Initially, it will provide a streamlined experience for developingFirefox Extensions.

• Getting started with web-ext
• Command reference

Here are the commands you can run. Click on each one for detailed documentation or use--help on the command line, such asweb-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 theweb-ext documentation in a browser

First, make sure you are running the currentLTS(long term support) version ofNodeJS.

You can install this command onto your machine globally with:

npm install --global web-ext

Alternatively, you can install this command as one of thedevDependenciesof your project. This method can help you control the version ofweb-extas used by your team.

npm install --save-dev web-ext

Next you can use theweb-ext command in your project as annpm script.Here is an example where the--source-dir argument specifies where to findthe source code for your extension.

package.json

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

You can always pass in additional commands to your npm scripts usingthe-- suffix. For example, the previous script could specify the Firefoxversion on the command line with this:

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

The community maintains aweb-ext formula.

brew install web-ext

You'll need:

• Node.js (currentLTS)
• npm, 8.0.0 or higher is recommended

Optionally, you may like:

• nvm, which helps manage node versions

If you had already installedweb-ext from npm,you may need to uninstall it first:

npm uninstall --global web-ext

Change into the source and install all dependencies:

git clone https://github.com/mozilla/web-ext.gitcd web-extnpm ci

Build the command:

npm run build

Link it to your node installation:

npm link

You can now run it from any directory:

web-ext --help

To get updates, just pull changes and rebuild the executable. You don'tneed to relink it.

cd /path/to/web-extgit pullnpm run build

Note: web-ext is primarily a command line tool and there is limited support for direct use of its internal API. Backward incompatible changesmay be introduced in minor and patch version updates to the web-ext npm package.

Aside fromusing web-ext on the command line, you may wish to executeweb-ext in NodeJS code.

As of version7.0.0, theweb-ext npm package exports NodeJS native ES modules only. If you are using CommonJS, you will have to usedynamic imports.

You are able to execute command functions without any argument validation. If you want to executeweb-ext run you would do so like this:

importwebExtfrom'web-ext';webExt.cmd.run({// These are command options derived from their CLI conterpart.// In this example, --source-dir is specified as sourceDir.firefox:'/path/to/Firefox-executable',sourceDir:'/path/to/your/extension/source/',},{// These are non CLI related options for each function.// You need to specify this one so that your NodeJS application// can continue running after web-ext is finished.shouldExitProgram:false,},).then((extensionRunner)=>{// The command has finished. Each command resolves its// promise with a different value.console.log(extensionRunner);// You can do a few things like:// extensionRunner.reloadAllExtensions();// extensionRunner.exit();});

If you would like to run an extension on Firefox for Android:

import*asadbUtilsfrom"web-ext/util/adb";// Path to adb binary (optional parameter, auto-detected if missing)constadbBin="/path/to/adb";// Get an array of device ids (Array<string>)constdeviceIds=awaitadbUtils.listADBDevices(adbBin);constadbDevice= ...// Get an array of Firefox APKs (Array<string>)constfirefoxAPKs=awaitadbUtils.listADBFirefoxAPKs(deviceId,adbBin);constfirefoxApk= ...webExt.cmd.run({target:'firefox-android',  firefoxApk,  adbDevice,sourceDir: ...}).then((extensionRunner)=>{...});

If you would like to control logging, you can access the logger object. Here is an example of turning on verbose logging:

import*aswebExtLoggerfrom'web-ext/util/logger';webExtLogger.consoleStream.makeVerbose();webExt.cmd.run({sourceDir:'./src'},{shouldExitProgram:false});

You can also disable the use of standard input:

webExt.cmd.run({noInput:true},{shouldExitProgram:false});

web-ext is designed for WebExtensions but you can try disabling manifest validation to work with legacy extensions. This is not officially supported.

webExt.cmd.run({sourceDir:'./src'},{getValidatedManifest:()=>({name:'some-fake-name',version:'1.0.0',}),shouldExitProgram:false,},);

You can also usewebExt.cmd.sign() to request a signed xpi for a given extension source directory:

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

You can also access the internal signing module directly if you need to submit an xpi file without also building it.Note: submit-addon is internal web-ext module, using the webExt.cmd.sign() is the recommended API method.

import{signAddon}from'web-ext/util/submit-addon';signAddon({// NOTE: Please set userAgentString to a custom one of your choice.userAgentString:'YOUR-CUSTOM-USERAGENT',  apiKey,  apiSecret,amoBaseUrl:'https://addons.mozilla.org/api/v5/',id:'extension-id@example.com',xpiPath:pathToExtension,savedUploadUuidPath:'.amo-upload-uuid',channel:'unlisted',});

Yes! The web-ext tool enables you to build and ship extensions for Firefox.This platform stabilized inFirefox 48which was released in April of 2016.

Hi! This tool is under active development. To get involved you can watch the repo,file issues, create pull requests, orcontact usto ask a question.Read thecontributing section for how to develop new features.

This is a great question and one that we will ask ourselves for each new web-extfeature. Most WebExtension functionality is baked into the browsersthemselves but a complimentary command line tool will still be helpful.Here is a partial list of examples:

• File watching.
  • When you edit a file, you may need to trigger certain commands (tests,installation, etc).
• Integrating with services.
  • Mozilla offers some useful services such aslinting andsigningextensions.