DEV Community: CJ

A Dilettante's Guide to Linting

CJ — Mon, 07 Sep 2020 19:30:27 +0000

This article is a step-by-step, ground-up look at how the most popular Javascript linting tools can be used together to professionalize any codebase. The target audience is a beginner++ level; you've written some javascript code in your IDE and probably pushed it to GitHub, but you haven't necessarily worked with other developers or published any public projects. The coverage will focus on vanilla Javascript, but some React linting is included incidentally. A TLDR version is available for more experienced developers.

The specific commands used below are based on my personal development environment: MacOS 10.15 (Catalina) with Bash. If you're on Windows or Linux, the principles will remain the same but the exact commands may differ slightly.

With that out of the way, here are our goals:

Install ESLint locally, allowing us to check our code for style and syntax errors.
Set the AirBnB Style Guide as our default ruleset.
Install either Prettier or this fork of Prettier to enable more powerful auto-formatting whenever we save a .js file.
Integrate ESLint and Prettier into VS Code so that all formatting work can be handled directly within the editor.

If I've made any mistakes, as I'm sure I have, please file an issue on the associated GitHub repo.

GETTING STARTED

This article was my original inspiration. After trying it out, I've made some changes to stay closer to AirBnB's style guide docs while adding some additional context and explanation.

Please note: terminal commands will always be on their own line, pre-fixed with a $ sign. Don't include the $ when typing the command in the terminal; it's used here only to indicate "this is a terminal command you should enter."

This guide focuses exclusively on using ESLint & Prettier within VS Code, rather than via the ESLint CLI. You can stop the install process at a few different points, depending on how sophisticated you want to get:

Following Steps 0 through 2 will give you a working ESLint set-up within VS Code.
Continuing with Step 3 will add additional auto-formatting via Prettier.
Finally, the addendum provides more configuration options for tailoring ESLint to your particular needs and preferences.

PREREQUISITES

Basic command line skills: You can mostly copy-paste the commands in this guide, but knowing how to cd / ls / etc, as well as understanding flags (like <command> --help), will be a plus.
VS Code basics: I'm assuming that you're already using VS Code, and that you understand the basics of how to navigate around it.
npm installed & up-to-date: If you're not sure whether you have npm installed, type npm --version into your terminal and hit enter. If you see a number, it's already installed. If not, follow this link to install Node & npm. We'll need v6.9.0, so please update before proceeding if you're at v6.8.x or lower.

A similar tool called npx should be installed automatically with npm. To confirm, enter npx -v and look for the version number. If you'd like a little background on what exactly npm is, see the notes in the addendum.
Terminology => Linter: A linter is a program that parses your source code to detect syntax errors or styling inconsistencies. Linters are useful for making sure multiple developers can work on a shared project in a consistent code style with as few errors as possible. ESLint is a powerful configurable linter. Prettier, by contrast, is a narrowly-focused code formatter that auto-fixes many style issues. It works by taking an AST representation of your code and re-printing it according to predefined & opinionated style rules. (For a bit more info on Prettier's design principles & under-the-hood implementation, see this blog post).

STEP 0: Picking a folder

All of the commands below should be executed while in a single folder in your terminal, unless otherwise indicated. Whatever folder you pick will then contain your installed packages and configuration files. ESLint will be available to all files within that folder, as well as to files within any sub-folders.
For example, I've set up my main workspace along this path:

~/Desktop/Coding/Personal/

where ~ is my home folder (literally /Users/connorrose). ESLint & Prettier are installed in this Personal folder. The Personal folder, or directory, then contains multiple sub-folders, or sub-directories, each of which is a project I've created (or cloned from GitHub). Since these sub-folders are nested inside the folder where I installed ESLint and Prettier, the linter will have access to them. The individual projects are each tracked as their own separate git repositories, while the Personal folder itself is not tracked via git version control.

You don't have to copy my exact directory set-up; just make sure you pick an install folder that can contain all of the projects you want linted according to the same AirBnB style rules. Remember that every sub-folder will be following this configuration, so don't pick a folder that contains outside projects already following their own style guides. Once you've chosen a folder for installation, you should navigate to that folder within your terminal and move on to the next step.

STEP 1: ESLint

Initializing with npm

Before we get started, let's create a package.json file to keep track of what we install. You should already be in your terminal, within the folder you've chosen (hint: pwd). To create package.json with default values, we'll initialize via npm:

$ npm init --yes

This command will:

Initialize our current folder as an npm package. To over-simplify, npm packages are just folders containing code files and a completed package.json. It isn't relevant to us, but with a few tweaks we could technically publish our current folder and all the code it contains with npm.
Create a package.json file in the current directory. This file keeps track of the packages we'll be installing.
Set some default values within package.json, including a name, version number, and license. Since we're not publishing our folder on npm, we won't worry about any of these values. However, you can look through the docs for more information.

Installing ESLint

Next, to install the core ESLint package, enter:

$ npm install eslint --save-dev

You can safely ignore any npm WARN messages about missing descriptions or fields.

This command will:

Create a folder called node_modules, inside which all our packages will be installed.
Install the ESLint package within node_modules.
Register ESLint as a dev-dependency in package.json.
Install all the other packages ESLint depends on, as shown in npm's terminal output.
Create a package-lock.json file in the current directory. This file automatically keeps track of the version info of packages we install, as well as the required version numbers for any of their dependencies.

What's a dependency?

The --save-dev flag registers the package we just installed as a development dependency within package.json. Dev-dependencies are packages required only during the development phase, rather than in production. That is, they are packages that help us write our code, but they do not contribute any functionality to the code we deploy to users.

Installing AirBnB

Without changing folders, install the AirBnB configuration for ESLint:

$ npx install-peerdeps --dev eslint-config-airbnb

The eslint-config-airbnb package adds AirBnB's style guide as a ruleset within ESLint. However, these rules are not enabled automatically. We first need to set up our ESLint configuration file. Create a new file, in the same folder we've been working in, called .eslintrc.json:

$ touch .eslintrc.json

The leading dot in front of the filename is very important! You can read more on dotfiles in the notes. This configuration file is written in JSON format, which lets us store our ESLint settings as properties on a Javascript object. Using a standardized file format like JSON allows many different programs, including VS Code, to interact with our configured settings. The ESLint config file can also be written in Javascript or YAML, but JSON is the simplest for now.

Configuring ESLint

Open your new .eslintrc.json file in VS Code and copy in the following:

{
  "env": {
    "browser": true,
    "es6": true
  },
  "extends": ["airbnb"]
}

env: sets the environments in which we expect to run our code. We've enabled support for browser-based Javascript, as well as the modern Javascript features introduced by ES6 / ECMAScript 2015.
extends: specifies the ruleset(s) we want to follow. For us that's the AirBnB ruleset we added via eslint-config-airbnb. Our new ESLint configuration will be an extension of the rules in the AirBnB package.

ESLint is now installed with a working AirBnB ruleset. The next step will add our awesome new linting abilities to VS Code.

STEP 2: VS Code

Installing the extension

If you're not already in VS Code, open it up now. Open up the Extensions pane and search for ESLint by Dirk Baeumer. Click the Install button.

Updating VS Code settings

If you're not sure how to access Settings in VS Code, see the official docs before continuing. (Hint: CTRL+SHFT+P > "Open Settings")

With the ESLint extension installed, update the two settings shown below. You can either search for these by name in the Settings GUI, or directly paste the code into your VS Code settings.JSON file:

  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",

editor.CodeActionsOnSave lets VS Code use ESLint to automatically re-format many of our style issues whenever we save a file.
editor.defaultFormatter sets the ESLint extension as our default formatter for all files in VS Code.

If you want to explore all of the VS Code settings available for ESLint, check out the extension documentation.

And that's it! You should now see ESLint highlighting any errors in your Javascript files, and it should even fix a few simple style mistakes on save, such as single versus double quotes or missing semicolons. If you're not seeing any of this, check the notes for some trouble-shooting tips.

If you're happy with what's been enabled so far, feel free to stop here. You'll still have a working linter in VS Code. However, if you want more powerful auto-formatting, including automatic line breaks for long lines (think lots of function parameters), then continue to Prettier in Step 3.

STEP 3: Prettier

Choosing a Prettier version

Before we continue, we have to decide which Prettier we want to use. Let me explain.

Prettier works magic. It takes long lines, breaks them up logically, and re-formats all sorts of other little consistencies that crop up in our code over time. To do this efficiently, Prettier has very few user-configurable options; most formatting decisions are hard-coded in. Unfortunately, one of these hard-coded decisions presents a major conflict with our chosen style guide: where you place your operators around linebreaks. Prettier will always move your operators to the end of a line, while AirBnB prefers operators at the start of a newline. People seem to have strong opinions about this issue, and I've ultimately sided with the start-of-line AirBnB camp (cleaner git diffs, easier to read, etc). Before you continue, I suggest doing a little research and following your heart on this one.

Installing Prettier

If you're fine with operators at the end of the line, continue with the normal Prettier install:

$ npm install --save-dev prettier

If you want your operators at the start of a newline, there's a fork for that! To install the forked version of Prettier with leading operators, use this command instead:

$ npm install --save-dev prettier@npm:@btmills/prettier

By using the <alias>@npm:<package> syntax, we've installed the forked package under the name prettier. This will let the other packages we're about to add find the forked version when they look for Prettier by name.

Installing integration packages

Prettier is a standalone program, so we'll need two more packages to integrate it with ESLint. To install both packages:

$ npm install --save-dev eslint-config-prettier eslint-plugin-prettier

eslint-config-prettier turns off all the ESLint rules covered by Prettier's auto-formatting.
eslint-plugin-prettier allows us to apply Prettier's fixes directly from within ESLint. More on this later.

Updating ESLint configuration

To add our new Prettier tools into our ESLint configuration, open the same .eslintrc.json file as before. You can copy/paste the below code exactly as-is, overwriting the current contents:

{
  "env": {
    "browser": true,
    "es6": true
  },
  "extends": ["airbnb", "prettier"],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": ["error"]
  }
}

Here's what we just did:

We've extended our configuration with Prettier (really eslint-config-prettier) in addition to AirBnB. Since Prettier is second in the array, its configuration will be applied after AirBnB, overwriting any conflicting rules. If you add additional rulesets in the future, you'll almost always want to keep Prettier last.
The new plugins property connects our eslint-plugin-prettier package to ESLint. This allows ESLint to directly call Prettier for auto-formatting our code.
The "prettier/prettier": ["error"] property within rules lets ESLint show Prettier's style warnings as normal ESLint errors. This works in connection with the eslint-plugin-prettier package.

Configuring Prettier

Prettier has it's own configuration file called .prettierrc.json. Create it now:

$ touch .prettierrc.json

Take note of the leading dot! We need to override two of Prettier's default settings, so open your new .prettierrc.json file and paste in the following:

{
  "printWidth": 100,
  "singleQuote": true
}

This sets our preferred line length to 100 characters and our default string format to single quotes instead of double quotes. These updates bring us in line with AirBnB.

And that's it! You're done. You should now see ESLint highlighting all of your errors in VS Code, and Prettier auto-formatting your style when you save. If you'd like to customize your set-up even further, head on over to the addendum.

... but what about the Prettier VS Code extension? We don't need it. Because eslint-plugin-prettier already connects Prettier's formatter to ESLint, we can rely on the ESLint extension alone. Every time ESLint's formatter is called on save, it will automatically add Prettier's formatting on top. One less thing to worry about!

A Dilettante's Guide to Linting: Addendum

CJ — Mon, 07 Sep 2020 19:27:10 +0000

If you made it to the end of the previous article with everything working, you're in great shape. You can safely call it a day and have a working set-up for many .js files to come. If you want to tailor your environment a bit more, this addendum will walk you through common additional settings. You can enable some or all of these to personalize your environment and/or enforce stricter style adherence than the simple config detailed previously. If you're interested, you can view my complete ESLint config file here.

Reference Docs

If you want to explore the settings on your own, the following links are good places to start. For the packages, don't be afraid to dig around in the source code! It's a great way to understand more about how things function and interconnect under-the-hood.

VS Code setting specificity

When we updated our VS Code settings in Step 2, we enabled ESLint for all file types, not just Javascript. This shouldn't cause any issues, as ESLint won't parse non-Javascript files. However, if you decide to set up other formatters for non-Javascript files, you'll want change your VS Code settings to target the ESLint extension more narrowly. You can do this with language specific editor settings:

  "[javascript]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint",
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": true
    }
  },

.prettierrc options

As discussed, Prettier doesn't let us do a whole lot of configuration. We only needed to change two options to match AirBnB, but we can customize a few more if we want. My Prettier config file specifies all the options I'm opinionated about, even though I'm just re-stating the default behavior for most of them.

String Format Power-Ups

One set of rules that breaks during Prettier / ESLint integration is string templating. We want to avoid template literals unless necessary, but always prefer template literals over string concatenation. To re-enable this behavior, we need to add an explicit rule in our .eslintrc.json file:

{
  //env, preset, ...
  "rules": {
    //... other rules
    "quotes": [
      "error",
      "single",
      { "avoidEscape": true, "allowTemplateLiterals": false }
    ],
    //... more rules
  }
}

Environment Globals: the latest and greatest

Environments in ESLint are just sets of global variables. By specifying an environment, we tell ESLint to not mark these variables as errors when we use them in a file without having provided our own explicit definition. Globals can include keywords like Set, for ES6 code, or the window object, for browser-based code. You can specify as many different or overlapping environments as you want, but you shouldn't start enabling everything without good reason. If we're working exclusively on browser-based code, leaving Node out of our environment list will ensure we don't sneak in any Node-specific globals by mistake. These are a few of the most common environments you might encounter:

browser: Covers all the browser-specific globals, like document or window, available to front-end code.
node: Covers the globals available to back-end code within Node's runtime environment.
es2020: This lets us use all the Javascript language features up through the most recent ECMAScript spec, including features from earlier specs like ES6. If your code will be executed in a runtime environment that doesn't support these features yet (and you're not using a transpiler), you may want to specify es6 instead.
jquery: If you use jQuery, this will save you from $-operator warnings.
jest: Eliminates errors for built-in Jest syntax like describe() and test().

Additional ESLint Rules (or, why eslint-config-airbnb isn't enough)

ESLint supports three levels of warning for most rules. You can set rules to a specific warning level to group your errors in whatever way works for you:

0 or "off": the rule will not be flagged whatsoever in your code.
1 or "warn": you'll see a yellow or orange squiggly, and the rule will be counted in the ⚠ status bar symbol within VS Code.
2 or "error": normal error, red squiggly, counted with ⓧ in VS Code status bar.

If you've gotten this far, you may have noticed some rules from the AirBnB style guide aren't showing as warnings or errors. If you dig into the package source code, you'll see that not every rule specified in the style guide has actually been enabled! We can re-enable any of these omissions by adding them to the "rules" object in .eslintrc.json:

  "rules" {
    // Not all missing rules are listed here
    "default-case-last": "error",
    "default-param-last": ["error"],
    "no-useless-call": "error",
    "prefer-exponentiation-operator": "error",
    "prefer-regex-literals": "error",
    //...
  }

Nested Config Files

Sometimes you'll clone a project that already contains ESLint configuration file(s) and packages. If you have multiple configuration files in a nested directory structure, ESLint will automatically try to combine all those files until it hits your home directory. To prevent this behavior, add "root": true to the outermost .eslintrc* file you want included in the chain. Note that ESLint applies a hierarchy of filetypes when determining how to apply multiple config files within the same folder:

.eslintrc.js
.eslintrc.yaml
.eslintrc.yml
.eslintrc.json
.eslintrc
package.json

See the ESLint docs for more info. Additionally, be aware that Prettier uses a different precedence for it's config file extensions:

"prettier" key in package.json
.prettierrc file (containing either JSON or YAML)
.prettierrc.json, .prettierrc.yml, or .prettierrc.yaml
.prettierrc.js or prettier.config.js using module.exports
.prettierrc.toml

React!

Guess what - you've already set up coverage for React. The eslint-config-airbnb package we installed brought along eslint-plugin-react as a dependency, and the AirBnB ruleset we extended includes configuration for React. For maximum utility, we should still tweak a few settings:

Within `.eslintrc.json`

Add "prettier/react" as the last item in the "extends" array.

"extends": ["airbnb", "prettier", "prettier/react"],

Update "parserOptions" to support JSX syntax:

"parserOptions": {
  "ecmaFeatures": {
    "jsx": true
  }
}

Add any additional React-specific rules you may want:

  // just a few of the possible rules
  "react/prefer-stateless-function": ["warn"],
  "react/jsx-key": "warn",
  "react/no-direct-mutation-state": "error",
  "react/no-adjacent-inline-elements": "error"

Note: We don't need to add "react" as a plug-in, since eslint-config-airbnb already took care of that for us.

Within VS Code

If ESLint is enabled for all filetypes in VS Code, you can skip this step. If you added a Javascript selector to your ESLint settings, as described above, you'll want to target .jsx files as well:

  "[javascriptreact]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint",
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": true
    }
  },

And that's it! You should be all set to lint and auto-fix all your JS & JSX files within VS Code.

NOTES

Reminder

Prettier only fixes a narrow selection of style errors. It cannot fix most of the structural problems that ESLint catches. ESLint will still flag those additional errors, but you will need to manually review the warning-squigglies to address anything Prettier and ESLint couldn't fix automatically.

A few words on npm

npm is a package manager. It lets you use bits of code that other people have written, known as packages or modules, on your local machine (ie, your laptop / desktop / hotwired Motorola Razr / etc). These packages can either be installed globally, meaning they are accessible everywhere on your computer, or locally, meaning they are only available in a certain folder (or directory) and it's subfolders (or sub-directories). The folder that contains all of your project files & subfolders, including your npm modules, is sometimes called your project's root directory. Additionally, npm uses a package.json file to store and manage information about your project and its associated packages. This is a file written in JSON that tracks lots of information about your project, including info on the various packages you've installed. We're not working directly with the package.json file in guide, but it's helpful to know what it is.

Many npm packages also have dependencies. These are other packages that the main package requires in order to run correctly. Often these dependencies will be installed automatically with whatever package you wanted, but sometimes they will need to be installed manually. A normal dependency is one that your project relies on at runtime, like jQuery for a live webpage. A dev-dependency is one that is only required during the development process and is not necessary for your finished application to function. ESLint & Prettier are dev-dependencies. Less common, a peer dependency is one required for another package to run, but which it expects you to already have installed. This is usually done to avoid installing multiple versions of the same package when using plugins.

What the heck are dotfiles?!

Dotfiles are hidden files used to set the configuration for many different types of programs, including ESLint, Prettier, VS Code, Bash, and Zsh. They're called dotfiles because the filenames start with a leading . that renders them hidden from normal file viewers, including the ls command. To view hidden files within the terminal, you can use:

$ ls -a -l

where -a shows hidden files and -l displays the results as a list.

Checking if your install worked

Your ESLint squiggles should appear immediately on any files within your install directory and its sub-directories. However, if error highlighting or fixOnSave doesn't appear to be working, try the steps below before any additional troubleshooting:

Create a new file in your installation directory (or its sub-directories).
Save that file once, preferably with at least one line of content.
Edit the file in some way. You can paste in the test case provided below if you'd like. You should see errors being highlighted by ESLint.
Save the file again. At this point, many of the style errors (including line-length) should auto-fix.

Feel free to use this code example to check for a few different types of errors, but remember to edit it at least once if included in the initial save!

let testFunc = function funcName (longArgNumberOne, longArgNumberTwo, longArgNumberFour, longArgNumberFive) {
  return "should be single quote and needs semicolon"
}