web-ext

Run the web extension in the current directory in Firefox

$ web-ext run

$ web-ext run --source-dir [path/to/directory]

$ web-ext run --verbose

$ web-ext run --target firefox-android

$ web-ext lint

$ web-ext build

$ web-ext build --verbose

$ web-ext sign --api-key [api_key] --api-secret [api_secret]

web-ext command [options] [arguments]
Common commands:
web-ext run [options]
web-ext lint [options]
web-ext build [options]
web-ext sign [options]
web-ext add-xpi path/to/addon.xpi [options]
web-ext docs
web-ext help [command]

--help, -h
    Show help message and exit. Can be used for specific commands, e.g., web-ext run --help.

--version
    Show the web-ext version number and exit.

--verbose
    Enable verbose logging output for more detailed information during execution.

--source-dir path, -s path
    The directory containing your extension's source code. Defaults to the current working directory. Used by run, lint, build, sign.

--output-dir path, -o path
    The directory where output files (e.g., packaged XPI) will be saved. Used by build, lint.

--firefox path
    Path to the Firefox binary to use for running your extension. Used by run.

--firefox-profile name|path
    Specify a Firefox profile by name or path to use for running your extension. Used by run.

--devtools
    Open Firefox's developer tools window when the browser starts. Used by run.

--start-url url
    A URL to open in Firefox when it starts. Can be specified multiple times. Used by run.

--api-key key, -a key
    Your API Key (JWT issuer) for signing. Required by sign.

--api-secret secret, -s secret
    Your API Secret (JWT secret) for signing. Required by sign.

--channel type
    The release channel for signing, either listed (default) or unlisted. Used by sign.

--overwrite-dest
    Overwrite existing packaged XPI files in the output directory without prompting. Used by build.

--ignore-files glob
    A glob pattern of files/directories to ignore when building or linting the extension. Can be specified multiple times. Used by build, lint.

web-ext is a command-line tool developed by Mozilla to streamline the development workflow for browser extensions built using the WebExtensions API. It provides a comprehensive suite of commands designed to simplify common tasks faced by extension developers. Key functionalities include: running an extension in a temporary Firefox profile with live reloading during development (via web-ext run), linting extension source code to catch common issues and adhere to best practices (via web-ext lint), packaging an extension into a .zip file ready for distribution (via web-ext build), and submitting/signing extensions for publication on addons.mozilla.org (AMO) (via web-ext sign). While primarily focused on Firefox, the WebExtensions API it supports is largely cross-browser compatible, making web-ext a valuable tool for anyone developing extensions targeting modern browsers. It is distributed as an npm package, making it easily installable via Node.js's package manager.

`web-ext` requires Node.js and npm (Node Package Manager) to be installed on your system. The sign command requires a developer account on addons.mozilla.org (AMO) and corresponding API credentials (JWT issuer and secret) to securely sign your extensions. When using `web-ext run`, a temporary Firefox profile is typically created for the development session and deleted upon exit, ensuring a clean slate. Custom Firefox installations or specific profiles might be needed for advanced debugging scenarios. While the WebExtensions API is designed for cross-browser compatibility, `web-ext` itself is primarily tailored for Firefox development and publishing workflows.

To install web-ext, you need Node.js and npm installed. Then, use npm to install it globally:

npm install --global web-ext

This makes the web-ext command available in your terminal.

A common workflow with web-ext includes:

1. Development: Use web-ext run in your extension's source directory to launch Firefox with your extension loaded and automatically reload changes.

cd my-extension-folder
web-ext run

2. Linting: Before packaging, lint your code to catch common errors and warnings:

web-ext lint

3. Packaging: Create a distributable .zip file (XPI) of your extension:

web-ext build

4. Signing (for AMO): If you intend to distribute via Mozilla Add-ons, sign your packaged XPI:

web-ext sign --api-key JWT_ISSUER --api-secret JWT_SECRET

The `web-ext` command-line tool was developed by Mozilla as part of their significant transition from the legacy XUL/XPCOM-based add-on system to the standardized WebExtensions API. This shift, which began around Firefox 48 in 2016 and concluded with the release of Firefox Quantum (Firefox 57) in 2017, aimed to improve security, performance, and cross-browser compatibility for extensions. `web-ext` emerged as a crucial tool to support developers during this transition and beyond, providing a modern and efficient workflow for building, testing, and deploying WebExtensions. It centralizes common development tasks, simplifying processes that previously required manual steps or separate tools, and ensures compliance with new development guidelines and signing requirements for add-ons distributed via addons.mozilla.org.

npm(1), node(1), firefox(1), zip(1)