A command line tool to help build, run, and test web extensions
JavaScript Shell
Permalink
Failed to load latest commit information.
.githooks/commit-msg test: Changed changelog linting to check the pull request title (#704) Dec 28, 2016
.github docs: easier copy/paste version printing command Jan 10, 2017
artifacts Add Flow for program validation Feb 5, 2016
bin Fix ENOENT on running the --version cli option Mar 3, 2016
src refactor: changed named functions params to have Flow types (#726) Jan 10, 2017
tasks chore: Fixed the intermittent empty pull request title failures (#731) Jan 4, 2017
tests refactor: changed named functions params to have Flow types (#726) Jan 10, 2017
.babelrc refactor: use async/await syntax (#411) Sep 15, 2016
.conventional-changelog-lintrc chore: make changelog linting more sane (#559) Oct 6, 2016
.eslintrc chore: Added prefer-const to eslint and related changes (#700) Dec 22, 2016
.flowconfig Test: add more flow types (#424) Aug 12, 2016
.gitignore Add support for code coverage reports Mar 3, 2016
.npmignore fix: Fixed `Cannot find module '../dist/web-ext'` after installation Jul 11, 2016
.npmrc Add save-prefix setting via .npmrc Mar 2, 2016
.nsprc chore: Run the node security platform tool in continuous integration (#… Sep 27, 2016
.travis.yml test: Changed changelog linting to check the pull request title (#704) Dec 28, 2016
CODE_OF_CONDUCT.md chore: web-ext is governed by Mozilla's code of conduct (#645) Nov 23, 2016
CONTRIBUTING.md docs: minor edits to CLI developer docs (#748) Jan 11, 2017
Gruntfile.js test: Changed changelog linting to check the pull request title (#704) Dec 28, 2016
LICENSE chore: Adds git pre-push hook that validates commit message formatting ( Oct 3, 2016
README.md feat: Deprecated Node 0.12 for addons-linter support (#414) Aug 4, 2016
package.json fix(package): update source-map-support to version 0.4.9 (#752) Jan 15, 2017
webpack.config.js fix: added eslint rule for shorthand property assignment (#695) Dec 20, 2016

README.md

Web-ext

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

Build Status Coverage Status Dependency Status devDependency Status

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

Documentation

Installation from npm

npm install --global web-ext

Installation from source

You'll need:

  • Node.js, 4.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

Should I Use It?

The web-ext tool enables you to build and ship web extensions for Firefox. This platform stabilized in Firefox 48 but you may need to develop with a nightly build of Firefox for some newer web-ext features. If you are looking to ship an add-on that runs in older versions of Firefox, consider jpm.

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 web extension 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 web extension support?

First, note that jpm is still actively maintained by Mozilla right now. We decided not to patch jpm for web extension support (See jpm issue 445, discussion). Here's why.

Mozilla built cfx then deprecated it for jpm and now we're proposing a new tool. I know this is frustrating for developers but web extensions 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] web extension 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 web extensions 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 web extensions 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.