web-ext is a command line tool designed to speed up various parts of the WebExtension development process, making development faster and easier. This article explains how to install and use web-ext.
Installation
web-ext is a node-based application that you can install with the nodejs/npm tool. You must use npm
greater than 3.0.0 to install web-ext
. Run the command npm --version
to check what you have and upgrade it by running this in your terminal:
npm install --global npm
If you're on Windows, you'll need to follow these instructions to complete the npm upgrade.
Next, install web-ext using the following command:
npm install --global web-ext
You can test whether your installation worked by running the following command, which lists the installed web-ext version number:
web-ext --version
Using web-ext
Once you've installed it, you can test web-ext out. At this point, it is a good idea to have a sample WebExtension to try it out on — if you don't have one of your own, you can clone our webextensions-examples repo.
Testing out an extension
You can test an extension in Firefox by cd
'ing into your extension's root directory and entering the following command:
web-ext run
This will start up Firefox and load the extension temporarily in the browser, just like you could on the about:debugging page.
See the run reference guide to learn about all available options.
Automatic extension reloading
The run
command will watch your source files and tell Firefox to reload the extension after you edit and save a file. For example, if you changed the name
property in your manifest.json
file, Firefox would display the new name. This makes it easy to try out new features and see them immediately. If you run into unexpected behavior with the reloading feature, please file a bug. You can also disable reloading like this:
web-ext run --no-reload
Testing in different versions of Firefox
To run your extension in a version of Firefox other than the default, use the --firefox-binary
option to specify a full path to the binary file. Here is an example on Mac OS:
web-ext run --firefox-binary=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin
On Windows, the path needs to include the firefox.exe
part, for example:
web-ext run --firefox-binary="C:\Program Files\Mozilla Firefox\firefox.exe"
Using a custom profile
By default, the run
command will create a temporary Firefox profile. You can run your extension with a specific profile using the --firefox-profile
option, like this:
web-ext run --firefox-profile=chris-work-profile
This option accepts a string containing the name of your profile or an absolute path to the profile directory.
When using a custom profile, web-ext
first copies the profile. The custom profile will not be altered.
Packaging your extension
Once you've tested your extension and verified that it's working, you can turn it into a package for submitting to addons.mozilla.org using the following command:
web-ext build
This will output a full path to the generated .zip
file that can be loaded into a browser. It is designed to automatically ignore files that are commonly unwanted in packages, such as .git
, node_modules
, and other artifacts.
See the build reference guide to learn more.
Distributing your own WebExtension
You can also self-host your package file for distribution but it needs to be signed by Mozilla first. The following command packages and signs a ZIP file, then returns it as a signed XPI file for distribution:
web-ext sign --api-key=yourapikey --api-secret=yourapisecret
The API options are required to specify your addons.mozilla.org credentials.
--api-key
: the API key (JWT issuer) fromaddons.mozilla.org
needed to sign the extension. This should always be a string.--api-secret
: the API secret (JWT secret) fromaddons.mozilla.org
needed to sign the extension. This should always be a string.
See the sign reference guide to learn about all available options.
Specifying different source and destination directories
The above commands all use default directories for the extension source and artifact creation (e.g. built .zip
files). The defaults are:
- Source: The directory you are currently inside.
- Artifacts: A directory called
./web-ext-artifacts
, created inside the current directory.
You can specify different source and destination directories using the --source-dir
(or -s
alias) and --artifacts-dir
(or -a
alias) options when running your commands. Their values can be relative or absolute paths, but must always be specified as strings. Here is an example of specifying both options at the same time when building an extension:
web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips
Outputting verbose messages
If you want to see exactly what web-ext is doing when you run a command, you can include the --verbose
option (or the -v
alias). For example:
web-ext build --verbose
Viewing all commands and options
You can list all commands and options like this:
web-ext --help
Note: You can also use the -h
alias.
You can list options for a specific command by adding it as an argument:
web-ext --help run