How to add code linting for a Node.js project

Let’s talk quickly about what it is. According to wikipedia:

lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors, and suspicious constructs.

Its biggest benefit is to remove the opinionated personal preferences from codebases with multiple contributors. A function written by a developer should looks similar to another one written by someone else. It ensures homogeneity which in turn make the repository easier to maintain.

Code linting is important for any projects that are more than the trivial hello world example.

The the Node.js ecosystem, ESLint is by far and away the most popular linter.

Following are the steps to add and configure ESLint for a Node.js repo.

Step 1. Add eslint npm package as a development dependency.

npm install eslint --save-dev

Step 2. Run eslint init and follow the wizard

./node_modules/.bin/eslint --init

I mostly use Node.js for backend projects, so my answers tend to be:

✔ How would you like to use ESLint? · style
✔ What type of modules does your project use? · commonjs
✔ Which framework does your project use? · none
✔ Does your project use TypeScript? · No / Yes
✔ Where does your code run? · node
✔ How would you like to define a style for your project? · guide
✔ Which style guide do you want to follow? · standard
✔ What format do you want your config file to be in? · JavaScript

The most notable of the questions above is about style guide. I find standard to be the most agreeable and stick with it for all of my projects.

Afterwards, ESLint’s wizard will offer to install a some npm packages to help check and enforce styles, e.g.

eslint-config-standard@latest eslint@^7.12.1 eslint-plugin-import@^2.22.1 eslint-plugin-node@^11.1.0 eslint-plugin-promise@^4.2.1
? Would you like to install them now with npm? › No / Yes

Once you have chosen yes, it will start download the packages.

Three files should be changed by the end of this step:

(1) In package.json file, new packages added under devDependencies. For the above choices, I have four new packages:
+ eslint-config-standard
+ eslint-plugin-import
+ eslint-plugin-node
+ eslint-plugin-promise

(2) New .eslintrc.js file at the project root with the following content:

(3) Changes to package-lock.json.

Step 3. Add npm scripts

The the following two properties to scripts property inside package.json

"lint": "eslint .  --ext .js"
"lint-fix": "eslint --fix .  --ext .js"

And now, you can run npm run lint to validate all the .js files in your project against the standard style. You can fix them all automatically by running npm run lint-fix 🎉

Step 4. Lint tests

If you use one of the popular test frameworks, there is a good chance that ESLint won’t be able to parse your tests, so far. This is because out of the box, ESLint only works with Javascript syntax and not the prevalent BDD style syntax that test frameworks converge.

To lint test files, you need plugins for ESLint.

Jest is a popular test framework for Node.js and is my go to option. We need Jest plugin, eslint-plugin-jest for ESLint.

Firstly, you need to install the dependency:

npm install --save-dev eslint-plugin-jest

Secondly, you need to add in the configuration for the plugin into .eslintrc.js file. My standard configuration file looks like this:

Detailed description of Jest’s plugin settings is available here.

After this step, npm run lint will validate and npm run lint-fix will fix all .js files in your project, including test files.

Step 5. Integrate ESLint into VS Code

If you, like me, use VS Code as the IDE for Javascript work, the ESLint extension is worth installing.

At the time of writing, the extension has more than 12M downloads so it is certainly useful enough for plenty of people. I find it really useful whilst not being too intrusive.

The extension can highlight code style errors, suggest solution and automatically fix the errors every time a file is saved.

Step 5. Lint file on save for VS Code

To configure ESLint to fix syntax automatically every time a file is save, you need to head to the settings me, i.e. the gear icon on the lower left of VS Code, or [Cmd,] shortcut on MacOS.

Within the settings menu, search for Code Actions on Save. The first option will say Editor: Code Actions on Save and below that, there will be an option to Edit in settings.json. Click the link to Edit in settings.json.

The settings.json file will open inside of your code editor. For ESLint to fix errors when you save your file, you will need to write the following code in settings.json:

"editor.codeActionsOnSave": {
  "source.fixAll.eslint": true
},
"eslint.validate": ["javascript"]

With this change saved to settings.json, VS Code will use ESLint to validate and fix your code for any style errors every time a .js file is saved.