Static Analysis tooling 🛠

Introduction

It's easy to forget that people have different ways to write their code, from indentation, writing conditional statements, to choosing what type of quotes to use for strings. While this is trivial when working on personal projects, it is another story for projects with different people simultaneously working on a single code base. Unable to agree on a coding style often leads to problems reviewing pull requests, with developers/project maintainers spending countless hours searching for formatting issues instead of focusing on the logic.

With this in mind, open-source projects need to include static analysis tooling, as they help improve code maintainability by spotting suspicious coding constructs or alerting us to common errors.

Choosing the right tool 🔍

For my static site generator, which is written in JavaScript, I have selected Prettier and ESLint as the formatting and styling guide tools. I chose them due to their popularity amongst other developers, with detailed documentation and high customizability. Also, I have been using Prettier for a while as a VS Code extension, so it would be nice to learn more about it.

Using Prettier 🎨

To set up Prettier, start by installing the tool using npm:

npm install --save-dev --save-exact prettier

Then, follow the instructions from the Prettier docs and create 2 files: .prettierrc and .prettierignore

.prettierrc is where you will set all the configuration options for your Prettier formatting.
.prettierignore lets the Prettier CLI and editors know which files to not format.

Finally, add the necessary scripts to package.json:

{
  // ...
  "scripts": {
    "prettier": "prettier --write \"./**/*.{md,jsx,json,html,css,js,yml}\"",
    "prettier-check": "prettier --check \"./**/*.{md,jsx,json,html,css,js,yml}\""
  }
  // ...
}

Using ESLint 🧪

To set up ESLint, start by installing the tool using npm:

npm install eslint --save-dev

After finishing the installation, follow by setting up a configuration file, which you can do with:

npx eslint --init

You should ended up with something like this:

module.exports = {
  env: {
    commonjs: true,
    es2021: true,
    node: true,
  },
  extends: ['eslint:recommended', 'prettier'],
  parserOptions: {
    ecmaVersion: 13,
  },
  rules: {
    semi: ['error', 'always'],
    quotes: ['error', 'double'],
  },
};

The configuration file is where you can customize the validation rules based on the project. For more information about the rules, using plugins, or adding shared settings, refer to the ESLint configuration docs.

Finally, add the necessary scripts to package.json:

{
  // ...
  "scripts": {
    "eslint": "eslint --config .eslintrc.js",
    "eslint-fix": "eslint --config .eslintrc.js --fix",
    "lint": "npm run eslint",
  },
  // ...
}

Editor Integration 💻

Running static analysis tools at build time (i.e., using our scripts) is great since we can automate it. However, it would be nice to have a way to integrate them into our editor or IDE so that we can enjoy the benefits while writing code.

My solution is to create a .vscode/ folder that contains settings.json, which directly configures the VSCode editor settings, and extensions.json, which stores ESLint and Prettier as the recommended extensions.

Adding a pre-commit hook 🎣

Lastly, how can we deal with forgetful developers? The answer: adding a Git pre-commit hook. The hook will run your source code formatter on any changes that are being committed, preventing formatting errors before the developer makes a pull request.

For this task, I'll be using husky and pretty-quick. husky is a package for defining and executing git hooks, while pretty-quick is used to run Prettier formatting against your staged files.

First, start by installing husky and pretty-quick:

npx husky-init && npm install
npm install --save-dev prettier pretty-quick

This will setup husky, modify package.json and create a sample pre-commit hook that you can edit.

Inside package.json, modify the pre-commit script to use pretty-quick:

{
  // ...
  "scripts": {
    "pre-commit": "pretty-quick --staged"
  },
  // ...
}

After that, add the following code to /.husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo '🐶 Checking your commit...'
npm run pre-commit || echo '❌ Build failed. Please fix the error(s) showed above.'

And that's it! Every time you make a commit, the pre-commit hook will make sure to format the code using the configurations from .prettierrc.

Cheers! 🍻

Blog