ESLint

In order to help people write standard-compliant code from the start and avoid wasting time during code reviews, a set of ESLint configuration files have been added to the code base so that JavaScript can be analyzed automatically.

This automatic linting can happen either while coding, in a code editor, or when using the command line. It also runs on treeherder for every check-in.

Running ESLint

ESLint comprises of a set of rules that are used to analyse the code for correctness and style consistency. Meeting these rules before review will help reduce the amount of review time, and the revisions necessary to have a review granted.

Setting up ESLint

./mach eslint --setup

Running ESLint

Eslint can be run via:

./mach lint -l eslint

You can limit running it to a specific directory with:

./mach lint -l eslint browser/components

Or work directory changes:

./mach lint -l eslint -w

Or outgoing commits only:

./mach lint -l eslint -o

See ./mach eslint --help for more options when running eslint.

VCS Hooks

Hooks are available for Mercurial & Git, see using a vcs hook for more details.

Editor Integration

It is highly recommended that you integrate eslint into your editor. This lets you see errors in real time, and can help you fix issues before you compile or run tests, reducing the time to develop patches.

See the ESLint user guide for which plugins to install in your editor.

Understanding Rules and Errors

Not all files are linted

Currently ESLint runs on:

• .js
• .jsx
• .jsm
• .xml
• .html
• .xhtml

Additionally, some directories and files are ignored, see the .eslintignore file

Handling Errors

If your code fails an ESLint rule, you'll get an error similar to this:

/gecko/toolkit/mozapps/installer/js-compare-ast.js
  18:39  error  'snarf' is not defined.       no-undef (eslint)

If you don't understand a rule, you can look it up on eslint.org for more information about it.

Mozilla Specific Rules

There are some rules that are specific for the Mozilla code-base. These have the prefix mozilla/.

More information:

• Outline details of the rules
• Rule Source Code

Common issues and how to solve them

My editor says that "mozilla/whatever" is unknown

• Run ./mach eslint --setup
• Restart your editor
• If that doesn't work, check that you have your editor pointing to the correct node_modules folder.

Node.js is not recognized

• Add it to your PATH environment variable by running PATH="$PATH:/path/to/node.js/".

For Example: In Windows 10, if you have installed Node.js on "C:\nodejs", then the command should look like: export PATH=$PATH:/c/nodejs

Enabling ESLint for a new directory

• Remove the directory from .eslintignore (in the base directory of the repository)
• Fix errors that occur when running ./mach eslint path/to/dir, see also the no-undef rules below.

no-undef

The no-undef rule is currently being enabled throughout the code base. Here are some common issues:

• My script is imported into the global browser.xul scope.
  • Add a line like:
    • /* eslint-env mozilla/browser-window */
  • or enable the rule in a .eslintrc.js if it will apply to the whole directory.
• My script is a frame-script, or includes items that loaded into content scripts:
  • Add a line to tell eslint to use the frame-script environment:
    • /* eslint-env mozilla/frame-script */
• My script is a worker:
  • Add a line to tell eslint to use the worker environment:
    • /* eslint-env worker */
  • or, to use a chrome worker environment:
    • /* eslint-env mozilla/chrome-worker */
• My file uses Chrome/XBL specific globals
  • Either, specify the global at the top of the file:
    • /* globals MyChromeGlobal */
  • or, add to the global section toolkit/.eslintrc.js if it is widely used.
• Foo.jsm exports a symbol, but that is not recognised by ESlint
  • Check it is listed correctly in tools/lint/eslint/modules.json
• Using Services.scriptloader.loadSubScript?
  • You'll need to include the following just above it:
    • /* import-globals-from relative/path/to/file.js */
• do_check_eq, add_task not defined in a test directory.
  • Ensure there is a .eslintrc.js file that extends one of:
    • "plugin:mozilla/browser-test"
    • "plugin:mozilla/chrome-test"
    • "plugin:mozilla/mochitest-test"
    • "plugin:mozilla/xpcshell-test"
  • See other test directories for how to do this.
• I need to test that something isn't defined.
  • Do something like:
    • // eslint-disable-next-line no-undef
    • it.does.not.exist();

Need More Help?

Join the #eslint channel on irc.mozilla.org and ask away.