1. Installation
2. Update
3. Using web-ext
4. Check your code
5. Test and debug
6. Package, sign, and publish
7. Use the configuration file
8. Advanced topics
9. See also

web-ext is a Node-based application. You install it withbrew or theNodeJSnpm tool.

Install withbrew using:

brewinstall web-ext

Install withnpm using:

npminstall--global web-ext

web-ext requires the currentLTS (long-term support) versions ofNodeJS.

To test whether the installation worked, run the following command, which displays theweb-ext version number:

web-ext--version

Before you useweb-ext, locate an example extension. If you don’t have one, use one from thewebextensions-examples repo. If you want to start from scratch, use the community-developedboilerplating tool to start with a fresh extension.

Before trying out your extension with therun command or submitting your package toaddons.mozilla.org, use thelint command to ensure yourmanifest and other source files are error-free. If you setstrict_min_version in your extension’s manifest file, lint reports on the permissions, manifest keys, and web extension APIs used that are not available in that version.

To check your extension code,cd into your extension’s root directory and enter:

web-ext lint

This uses theaddons-linter library to walk through your source code directory and report any errors, such as declaring an unknown permission.

See thelint reference guide to learn more.

• Test your extension
• Automatically reload your extension
• Test in different versions of Firefox
• Test in Firefox for Android
• Debug in Firefox for Android
• Test unsigned extensions
• Use a custom profile
• Keep profile changes

Test your extension

Test an extension in Firefox bycd'ing into your extension’s root directory and entering:

web-ext run

This starts Firefox and loads the extension temporarily in the browser, just as you can on theabout:debugging page. Note that thisweb-ext method has the samelimitations regarding prompts for permissions and restart features asabout:debugging.

See therun reference guide to learn more.

Automatically reload your extension

Therun command watches your source files and tells Firefox to reload the extension after you edit and save a file. For example, if you change thename property in yourmanifest.json file, Firefox displays the new name. This makes it easy to try out new features because you can see the effect immediately. The automatic reloading feature is active by default. You use it like this:

web-ext run

You can also press ther key in theweb-ext terminal to trigger an extension reload.

If you experience unexpected behavior with the reloading feature, pleasefile a bug. You can also disable reloading like this:

web-ext run --no-reload

Test in different versions of Firefox

To run your extension in a version ofFirefox Desktop other than the default, use the--firefox option to specify a full path to the binary file. Here is an example for Mac OS:

web-ext run--firefox=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin

On Windows, the path needs to includefirefox.exe, for example:

web-ext run--firefox="C:\Program Files\Mozilla Firefox\firefox.exe"

See therun command reference to learn more.

Test in Firefox for Android

To run your extension inFirefox for Android, follow the instructions toset up your computer and device.

With your device connected to your development computer, run:

web-ext run--target=firefox-android

This command displays the device ID for your connected Android device or devices. If you don't see a device ID, check that you set up the device correctly for development.

Now, add the device ID to the command:

web-ext run--target=firefox-android --android-device=<device ID>

If you've installed multiple versions of Firefox on the device, choose one like this:

web-ext run--target=firefox-android... --firefox-apk=org.mozilla.firefox

The first time you run this command, you may need to grant Android permissions for the APK. This is because the command needs read/write access to the device storage so that Firefox for Android can run on a temporary profile. Theweb-ext output guides you on how to grant these permissions.

Theweb-ext command does not alter your Firefox for Android preferences or data. To learn more about howweb-ext interacts with your device, run the command with--verbose.

See therun command reference to learn more.

Debug in Firefox for Android

When usingweb-ext run to test an extension on Firefox for Android, you see a message like this in the console output:

You can connect to this Android device on TCP port51499

This is a remote debugger port that you canconnect to with Firefox's developer tools. In this case, you connect to hostlocalhost on port51499.

Seethe Debug your extension guide for more information about debugging an extension on Firefox for Android.

Test unsigned extensions

When you executeweb-ext run, the extension is installed and remains installed until you close Firefox. This does not violate any signing restrictions. If instead you create a zip file withweb-ext build and try to install it into Firefox, you see an error telling you that the add-on is not signed. To install unsigned extensions, use anunbranded build ordevelopment build.

Use a custom profile

By default, therun command creates a temporary Firefox profile. To run your extension with a specific profile use the--firefox-profile option, like this:

web-ext run --firefox-profile=your-custom-profile

This option accepts a string containing the name of your profile or an absolute path to the profile directory. This is helpful if you want to configure settings for therun command.

Keep profile changes

Therun command does not save any changes made to the custom profile specified by--firefox-profile. To keep changes, use the--keep-profile-changes option:

web-ext run --keep-profile-changes --firefox-profile=your-custom-profile

This may be helpful if your extension has many different run states.

• Package your extension
• Sign and submit your extension for publication
• Sign and submit your updated extension for publication
• Sign your extension for self-distribution
• Sign in a restricted environment
• Sign a test version of a listed extension

Package your extension

After testing your extension and verifying that it's working, you can turn it into a package for submitting toaddons.mozilla.org using this command:

web-ext build

This outputs a full path to the generated.zip file that can be loaded into a browser.

web-ext build is designed to ignore files that are commonly not wanted in packages, such as.git,node_modules, and other artifacts.

See thebuild reference guide to learn more.

Sign and submit your extension for publication

When you have confirmed that your extension works as expected, you can publish it onaddons.mozilla.org. You can do this using the website orweb-ext sign. To useweb-ext sign you need to:

• if you're submitting a Manifest V3 extension, ensure that you've set an ID for the extension in its manifest.json file using the keybrowser_specific_settings.gecko.id.
• create a JSON file containing the metadata needed by addons.mozilla.org to list the extension.
• obtain an API key from addons.mozilla.org.

Create your metadata file

Metadata is required for the first version of an extension listed on AMO. This metadata can include any of the properties of theaddons.mozilla.org add-on API Create request JSON object. However, the"categories" and"summary" properties must be provided.

For example:

{"version":{"license":"MPL-2.0"},"categories":{"firefox":["shopping","bookmarks"]},"contributions_url":"https://donate.mozilla.org","requires_payment":false,"homepage":{"en-US":"http://example.org?lang=en-US","fr":"http://example.org?lang=fr"},"support_email":{"en-US":"support@example.org","fr":"support-fr@example.org"}}

Obtain your API key

Visit theaddons.mozilla.org credentials page. You must register if you haven't done so before. From this page you obtain:

• The JWT issuer key, a string that looks something likeuser:12345:67. You supply this toweb-ext sign as the API key in--api-key.
• The JWT secret, a string that looks something like634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009. You supply this toweb-ext sign as the API secret in--api-secret.

Runweb-ext sign

You can now runweb-ext sign supplying the API key and location of the JSON file containing the metedata.:

web-ext sign--channel=listed --amo-metadata=<path to your metadata JSON file> --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET

If you sign a Manifest V2 extension without an explicit ID,addons.mozilla.org generates an ID andweb-ext saves it to.web-extension-id in the working directory. Add the ID to the extension'sbrowser_specific_settings.gecko.id key in its manifest.json file. The ID needs to be present to publish updates withweb-ext.

See thesign reference guide to learn more.

Sign and submit your updated extension for publication

As you improve and update your extension you want to submit new versions for publication onaddons.mozilla.org. You can do this using the website orweb-ext sign. To useweb-ext sign you need to:

• ensure you've set the extension's ID in the manifest.json keybrowser_specific_settings.gecko.id.
• create a JSON file containing any updated metadata to be used on addons.mozilla.org.
• obtain an API key from addons.mozilla.org.

Create your metadata file

When publishing an extension update metadata isn't required. However, any of the properties of theaddons.mozilla.org add-on API Version Create request JSON object can be provided.

Obtain your API key

Visit theaddons.mozilla.org credentials page. You must register if you haven't done so before. From this page you obtain:

• The JWT issuer key, a string that looks something likeuser:12345:67. You supply this toweb-ext sign as the API key in--api-key.
• The JWT secret, a string that looks something like634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009. You supply this toweb-ext sign as the API secret in--api-secret.

Runweb-ext sign

You can now runweb-ext sign supplying the API key and location of the JSON file containing the metedata.:

web-ext sign--channel=listed --amo-metadata=<path to your metadata JSON file> --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET

See thesign reference guide to learn more.

Sign your extension for self-distribution

As an alternative to publishing your extension onaddons.mozilla.org, you can self-host your package file but it needs to besigned 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--channel=unlisted --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET

The API options are required to specify youraddons.mozilla.org credentials.

• --api-key: the API key (JWT issuer) fromaddons.mozilla.org needed to sign the extension. This is a string that will look something likeuser:12345:67.
• --api-secret: the API secret (JWT secret) fromaddons.mozilla.org needed to sign the extension. This is a string that will look something like634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009.

See thesign reference guide to learn more.

Sign in a restricted environment

If you're working in an environment that restricts access to certain domains, you can try using a proxy when signing:

web-ext sign --api-key=... --api-secret=... --api-proxy=https://yourproxy:6000

See the--api-proxy option to learn more.

The following domains are used for signing and downloading files:

• addons.mozilla.org
• addons.cdn.mozilla.net

Sign a test version of a listed extension

If you'velisted an extension onaddons.mozilla.org, useweb-ext to create a signed butunlisted version for testing purposes. For example, you may wish to distribute an alpha or beta version to users for early feedback and testing.

First, change the version number in yourmanifest.json so that it is different from the latest listed version. Then, create the unlisted version by using the--channel option like this:

web-ext sign--channel=unlisted --api-key=... --api-secret=...

This signs and downloads an XPI file that can be installed into Firefox.

See thesign reference guide to learn more.

• Set option defaults in a configuration file
• Automatically discover configuration files

Set option defaults in a configuration file

You can specify--config=my-config.cjs or--config=my-config.mjs to set default values for any option. Here is an example with thebuild command:

web-ext--config=my-config.mjs build

The file should be a CommonJS moduleas understood by NodeJS and must export each configuration value. Here is how you would set the default value of--verbose totrue:

exportdefault{verbose:true,};

If you want to specify options that only apply to a specific command, you nest the configuration under the command name. Here is an example of adding configuration for--overwrite-dest that only applies to thebuild command and--firefox that only applies to therun command:

exportdefault{// Global options:verbose:true,// Command options:build:{overwriteDest:true,},run:{firefox:'nightly',},};

To create a configuration key for a command line option, you remove the preceding dashes and convert the name to camel case. As you can see from this example,--overwrite-dest was converted tooverwriteDest.

If an option can be specified multiple times on the command line then you define it as an array. For example, here is how to specify multiple--ignore-files patterns:

exportdefault{ignoreFiles:['package-lock.json','yarn.lock',],};

web-ext also tries to load its configuration options from a"webExt" property included in thepackage.json file in the current directory:

{"name":"an-extension-src-dir-with-a-package-json","version":"1.0.0",  ..."webExt":{"sourceDir":"dist/extension/"}}

Automatically discover configuration files

web-ext loads configuration files in the following order:

• A config file named.web-ext-config.mjs in your home directory, for example:
  • On Windows:C:\Users\<username>\.web-ext-config.mjs
  • On macOS:/Users/<username>/.web-ext-config.mjs
  • On Linux:/home/<username>/.web-ext-config.mjs
• A config property named"webExt" included in apackage.json file in the current directory.
• A config file namedweb-ext-config.mjs in the current directory.

(web-ext also recognizes files named.web-ext-config.cjs as configuration files.)

If a home directory config and a local directory config define the same option, the value from the latter file is used.

For example, creating~/.web-ext-config.mjs containg:

exportdefault{"sign":{"apiKey":"<API_KEY>","apiSecret":"<API_SECRET>"}}

Is the equivalent of:

web-ext sign --api-key<API_KEY> --api-secret<API_SECRET>

To disable automatic loading of configuration files, set this option:

web-ext --no-config-discovery run

To diagnose an issue related to config files, re-run your command with--verbose. This tells you which config file affected which option value.

• Specify different source and destination directories
• Output verbose messages
• View all commands and options
• Detect temporary installation
• Use web-ext from a script

Specify different source and destination directories

The commands use default directories for the extension source and artifact creation (for example, built.zip files). The defaults are:

• Source: The directory you are in.
• Artifacts: A directory called./web-ext-artifacts, created inside the current directory.

You can specify different source and destination directories using the--source-dir and--artifacts-dir 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 when building an extension:

web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips

Output verbose messages

To see in detail what web-ext is doing when you run a command, include the --verbose option. For example:

web-ext build--verbose

View all commands and options

You can list all commands and options like this:

web-ext--help

You can list options for a specific command by adding it as an argument:

web-ext--help run

Detect temporary installation

Your extension can detect whether it was installed usingweb-ext run, rather than as a built and signed extension downloaded fromaddons.mozilla.org. Listen for theruntime.onInstalled event and check the value ofdetails.temporary.

Use web-ext from a script

You can useweb-ext as aNodeJS module. Here ismore information, with example code.

web-ext repo
web-ext command reference

Tags: guide installing packaging testing tools web-ext webextension 

Contributors: caitmuenster rebloor Sheppy kumar303 platy hellosct1 lgreco wbamberg andrewtruongmoz saintsebastian arai tofumatt chrisdavidmills ankushduacodes huyenltnguyen rebloor Jamesllllllllll TimWitzdam 

Last update: TimWitzdam Jul 31, 2024