Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    web-extpublic

    Web-ext

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

    Build Status Coverage Status Dependency Status devDependency Status

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

    Documentation

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

    Installation from npm

    First, make sure you are running the current LTS (long term support) version of NodeJS.

    Global command

    You can install this command onto your machine globally with:

    npm install --global web-ext
    

    For your project

    Alternatively, you can install this command as one of the devDependencies of your project. This method can help you control the version of web-ext as used by your team.

    npm install --save-dev web-ext
    

    Next you can use the web-ext command in your project as an npm script. Here is an example where the --source-dir argument specifies where to find the 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 using the -- suffix. For example, the previous script could specify the Firefox version on the command line with this:

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

    Installation from source

    You'll need:

    • Node.js, 6.0.0 or higher
    • npm, 3.0.0 or higher is recommended

    Optionally, you may like:

    • nvm, which helps manage node versions

    If you had already installed web-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.git
    cd web-ext
    npm install
    

    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't need to relink it.

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

    Using web-ext in NodeJS code

    Aside from using web-ext on the command line, you may wish to execute web-ext in NodeJS code. There is limited support for this. Here are some examples.

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

    // const webExt = require('web-ext').default;
    // or...
    import webExt from '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 control logging, you can access the logger object. Here is an example of turning on verbose logging:

    webExt.util.logger.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,
      },
    );

    Should I Use It?

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

    Get Involved

    Hi! This tool is under active development. To get involved you can watch the repo, file issues, create pull requests, or ask a question on dev-addons. Read the contributing section for how to develop new features.

    Some Questions and Answers

    Why do we need a command line tool?

    This is a great question and one that we will ask ourselves for each new web-ext feature. Most WebExtension functionality is baked into the browsers themselves 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 as linting and signing extensions.

    Why not patch jpm for WebExtensions support?

    First, note that jpm is still actively maintained by Mozilla right now. We decided not to patch jpm for WebExtensions support (See jpm issue 445, discussion).

    Mozilla built cfx then deprecated it for jpm and now we're proposing a new tool. I know this is frustrating for developers, but WebExtensions mark a major turning point. It would be an arduous task to wedge its feature set and simplified development process into jpm.

    Pros of creating a new tool:

    • By creating a new tool that focuses on the [emerging] WebExtensions standard, we have a better chance of interoperating with other platforms, such as Google Chrome or Opera. It would be hard to do that while preserving compatibility in jpm.
    • Creating SDK-based add-ons was overly complicated. With WebExtensions you no longer need to convert your source into legacy artifacts and you won't need boostrapping scripts.
    • There are superior features in Firefox now for developing extensions such as loading from source code instead of a packaged XPI. It will be easier to reimagine a new tool around these work flows rather than adjust jpm's existing work flows.
    • jpm's functional tests are slow, brittle and hard to run. There are flaky time-outs and we've run out of low hanging fruit fixes at this point.
    • Most of jpm's code was not designed to be unit testable which makes it hard to maintain and refactor.
    • jpm's code was written in ES5 which is cumbersome after coming from the ES6 Firefox code base or from most other languages with modern conveniences (Python, Ruby, etc).
    • Some core functionality of jpm can be extracted and re-used in the new tool.

    Cons of creating a new tool:

    • Firefox extension developers will have to interrupt and re-arrange their work flows.
    • Developers of existing add-ons will need to port to WebExtensions sooner rather than later.
    • The web-ext tool will require some ramp-up time for scaffolding.
    • The community of jpm contributors will need to shift focus to web-ext.

    install

    npm i web-ext

    Downloadsweekly downloads

    4,659

    version

    2.7.0

    license

    MPL-2.0

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar