Canonical ESLint Config

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:

{
  "extends": "canonical/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 – The Canonical code style guide.
• canonical/ava – for projects that use AVA.
• canonical/browser – for projects that use DOM and other browser APIs.
• canonical/cypress – for projects that use Cypress.
• canonical/flowtype – for projects that use Flowtype.
• canonical/graphql – for projects that use GraphQL.
• canonical/jest – for projects that use jest.
• canonical/jsdoc – for projects that use JSDoc.
• canonical/json – for projects that use JSON.
• canonical/jsx-a11y – for projects that use React and want to include accessibility checks.
• canonical/lodash – for projects that use lodash.
• canonical/mocha – for projects that use Mocha.
• canonical/module – for projects that use ESM modules.
• canonical/next – for projects that use Next.js.
• canonical/node – for projects that use Node.js.
• canonical/prettier – applies Prettier formatting.
• canonical/react – for projects that use React.
• canonical/regexp – for projects that use regular expressions.
• canonical/typescript-type-checking – for projects that use TypeScript and want additional rules that require type information (rules using type information take longer to run).
• canonical/typescript – for projects that use TypeScript.
• canonical/vitest – for projects that use Vitest.
• canonical/yaml – for projects that use YAML.
• canonical/zod – for projects that use Zod.

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]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[html]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[javascript]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[json]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[markdown]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[typescript]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[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:

• jest-eslint-runner
• Integrations

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