WebExtensions/Hacking

Code Style

WebExtension JavaScript code follows the Mozilla [coding style guide], with the following differences:

• === may be used in favor of == when doing so makes sense.
• The opening brace in function statements or expressions should be on the same line as the function keyword.
• let or const should be used in place of var wherever possible.
• Function arguments and variable names should never use Hungarian Notation.
• All JavaScript files or inline <script> nodes must begin with "use strict";
• All members in multi-line object or array literals must be followed by a comma, including the last.

ESLint will enforce most of these rules.

Checking your code with ESLint

All WebExtension directories in mozilla-central are configured with a set of ESLint rules, which all code is required to pass. Many of these rules help to catch serious errors, such as references to non-existent variables, or a missing trailing comma turning an array literal into an array dereference, so it is extremely important that you check you code against them before it lands.

The simplest way to check your code is using the mach eslint command. This requires that you have [NPM] installed (and, if you're on Linux, it may require that you [fix NPM permissions]).

To setup ESLint, you need to run the following once:

./mach eslint --setup

This should install ESLint, along with the necessary plugins. After that's done, you can check the files you've been working on with the following:

./mach eslint path/to/file.js

Or you can check all WebExtension code with:

./mach eslint toolkit/components/extensions browser/components/extensions toolkit/modules/addons

Integrating ESLint with your editor

Since manually checking your code isn't always practical (and is easy to forget), it's best to integrate automatic checking with your code editor. Many editors [have integration plugins], or built-in support.

Some editors may need special settings to work well with our codebase. Feel free to add other editors below, as you see fit.

Vim

The easiest way to integrate ESLint with Vim is using the [Syntastic plugin].

The following assumes that you use the [Vundle package manager]. It should be easy enough to adapt to any other package manager you happen to prefer, though.

You should configure Syntastic roughly as follows:

" Initialize Vundle.
filetype off
call vundle#rc()

" Enable the Syntastic bundle.
Bundle 'scrooloose/syntastic'

" Enable ESLint in Syntasitc.
let g:syntastic_javascript_checkers = ['eslint']

" Enable the HTML plugin, and enable JavaScript linting for HTML files.
let g:syntastic_javascript_eslint_args = ['--plugin', 'html']
let g:syntastic_filetype_map = { "html": "javascript" }

After you've added this to your configuration (and have installed Vundle, if necessary), launch Vim and run:

:BundleInstall

This will install the Syntastic plugin. After this, you should be good to go.

Version control hooks

The mozilla-central tree contains a Mercurial plugin to automatically check any changed files, using ESLint, when you commit. This can be enabled by adding the following to your global .hgrc file, or to .hg/hgrc in your repository:

[extensions]
# Replace "~/src/mozilla-central/" with the full path to your mozilla-central repository.
mozeslint = ~/src/mozilla-central/tools/mercurial/eslintvalidate.py

Now Mercurial will check your code for you, and show any warnings or errors, every time you commit.