Awesome
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
:
// 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
– 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/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 usingcanonical/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
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:
- Run
npm run generate-typescript-compatibility-rules
script. It disables and override any TypeScript rules that are incompatible with ESLint built-in rules. - Run
npm run compare
script. It generates ruleset comparison table, updates README.md, and identifies rules that are not configured.