Home

Awesome

Canonical ESLint Config

NPM version

The most comprehensive code style guide.

Canonical consists of 1,000+ rules (40% auto-fixable), some of which are custom written for Canonical. Canonical goal is to reduce noise in code version control and promote use of the latest ES features.

Usage

Most projects should simply extend from canonical/auto:

// eslint.config.js
import auto from 'eslint-config-canonical/configurations/auto';

export default [
  ...auto
];

Rulesets

Note Most projects should just use canonical/auto and override settings when necessary for individual frameworks or file patterns (e.g. vitest vs ava).

This package includes the following rulesets:

canonical/auto ruleset

canonical/auto is a special ruleset that uses overrides to only apply relevant style guides. This reduces the linting time and the number of false-positives.

canonical/auto can be fine-tuned using overrides just like any other ESLint ruleset, e.g.

{
  "extends": [
    "canonical/auto"
  ],
  "overrides": [
    {
      "extends": [
        "canonical/jsx-a11y"
      ],
      "files": "*.tsx"
    },
    {
      "extends": [
        "canonical/vitest"
      ],
      "files": "*.test.{ts,tsx}"
    }
  ],
  "root": true
}

Compatibility with Prettier

For the most part, Prettier and Canonical are already compatible. There are only a few transformations that are incompatible, e.g. Prettier enforces line-length and Canonical does not. As such, there is no good reason to use both. However, if you wish to use Prettier, you can do so by using canonical/prettier ruleset, which uses eslint-plugin-prettier to apply Prettier formatting after applying Canonical rules.

{
  "extends": [
    "canonical",
    "canonical/jsdoc",
    "canonical/regexp",
    "canonical/react",
    "canonical/typescript",
    "canonical/jest",
    "canonical/prettier"
  ]
}

Note The reason for using Prettier as an ESLint plugin (as opposed to a separate tool) is because having multiple tools that apply formatting complicates IDE and other tooling setup.

Note Your local .prettierrc is going to be ignored when using canonical/prettier.

Compatibility with other style guides

Since Canonical style guide includes more rules than any other style guide, you can have your codebase compatible with a specific style guide (e.g. airbnb) and benefit from Canonical for rules that are not covered by the other guide. All you have to do is extend from the Canonical style guide before extending from the desired style guide, e.g.

{
  "extends": [
    "canonical",
    "canonical/jsdoc",
    "canonical/regexp",
    "canonical/react",
    "airbnb"
  ]
}

Integrations

Visual Studio Code

Use the dbaeumer.vscode-eslint extension that Microsoft provides officially.

Example .vscode/settings.json:

{
  "eslint.validate": [
    "css",
    "html",
    "javascript",
    "javascriptreact",
    "json",
    "markdown",
    "typescript",
    "typescriptreact",
    "yaml"
  ]
}

The setting below turns on Auto Fix for all providers including ESLint:

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

Additionally, we found it that being explicit about which formatter you are using for each file improves DX:

{
  "[css][html][javascript][javascriptreact][json][markdown][typescript][typescriptreact][yaml]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  }
}

While not required if you've configured explicit formatter for each file type, I advise that you explicitly disable prettier extension in your project:

{
  "prettier.enable": false,
}

Sharing these settings in your project should be sufficient to prevent local settings accidentally overriding the desired formatter behavior.

Benchmark

Canonical vs Prettier

This benchmark compares running ESLint using Canonical style guide against a project with 3,000+ files VS linting the same project using Prettier.

System:
  OS: macOS 11.6
  CPU: (16) x64 Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz
  Memory: 64.00 GB
npmPackages:
  eslint: 8.1.0
  prettier: 2.4.1

As you may expect, Prettier is going to complete checks quicker – this is because it runs a lot fewer transforms and it only runs style checks (as opposed to static analyses).

The first time you run ESLint, it will take significantly more time. However, if you enable --cache, then the follow up checks will complete in no time.

$ time prettier src
27.06s user
1.74s system
166% cpu
17.335 total

$ eslint --cache src
182.43s user
9.13s system
126% cpu
2:31.22 total

$ eslint --cache src
1.96s user
0.39s system
107% cpu
2.188 total

Using ESLint cache will dramatically improve ESLint running time by ensuring that only changed files are linted. This is useful if you are using ESLint to run pre-commit / pre-push git hooks or otherwise depend on these checks completing in real-time.

Additionally, if performance is a consideration, you may consider:

These options provide near instant feedback just how you are used to when using Prettier.

Table of Comparison

COMPARISON_TABLE.md

Versioning Policy

All breaking changes will bump the major version as per the semver convention. Therefore, every new rule addition will increase the major version.

Development

First, run npm install and then npm run setup-dev. Then, any time that ESLint dependencies are updated you must:

  1. Run npm run generate-typescript-compatibility-rules script. It disables and override any TypeScript rules that are incompatible with ESLint built-in rules.
  2. Run npm run compare script. It generates ruleset comparison table, updates README.md, and identifies rules that are not configured.

Incompatible rules

INCOMPATIBLE_RULES.md