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.
// eslint.config.tsimport auto from 'eslint-config-canonical/auto';import tseslint from 'typescript-eslint';export default tseslint.config(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).
canonical/browser – for projects that use DOM and other browser APIs.
– for projects that use .
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.
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.
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.
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.
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.
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-pushgit hooks or otherwise depend on these checks completing in real-time.
Additionally, if performance is a consideration, you may consider:
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.
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).