eslint-config-canonical

47.4.2 verified Sat Apr 25 auth: no javascript

A comprehensive ESLint shareable config with 1,000+ rules (40% auto-fixable) and custom ESLint plugin. Current stable version: 47.4.2. Released frequently (10+ versions in recent months). Key differentiators: includes auto-detection ruleset that only applies relevant style guides based on project files, supports many frameworks (React, Next.js, TypeScript, GraphQL, Lodash, etc.) and tools (Jest, Vitest, Mocha, AVA). Requires ESLint ^9 and is ESM-only. No CJS support. Custom rules in eslint-plugin-canonical.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/eslint-config-canonical/auto.js not supported. ↓

cause Using CommonJS require() with v47 which is ESM-only.

fix

Use import syntax or set "type": "module" in package.json. Alternatively use dynamic import: const auto = (await import('eslint-config-canonical/auto')).default;

error Configuration for rule "canonical/filename-match-regex" is invalid. Value "string" is not a valid severity. ↓

cause Passing a string like 'off' without quotes or as wrong type globally.

fix

Use the correct severity: "off", "warn", or "error" as a string, or use number 0, 1, 2.

error Could not find plugin "canonical" in config. ↓

cause Missing eslint-plugin-canonical or not loaded properly.

fix

Ensure eslint-plugin-canonical is installed as a devDependency. In flat config, use plugins: { canonical: require('eslint-plugin-canonical') } or import.

error TypeError: Cannot read properties of undefined (reading 'configs') ↓

cause Importing from 'eslint-config-canonical' without a subpath, expecting named exports that no longer exist.

fix

Use path imports like 'eslint-config-canonical/auto' or import * as configs and use configs.react etc. (note: subpath imports are recommended).

Warnings

breaking ESM-only in v47. CommonJS require() will fail with ERR_REQUIRE_ESM. ↓

fix Switch to ESM imports. If using CommonJS, use dynamic import or stay on v46.

deprecated Named exports (e.g., import { react } from 'eslint-config-canonical') are deprecated. ↓

fix Use path imports: import react from 'eslint-config-canonical/react';

gotcha auto ruleset uses overrides based on detected files; may not pick up all frameworks in monorepos. ↓

fix Explicitly include framework-specific configs (e.g., react, next) in overrides with explicit file patterns.

breaking Requires ESLint ^9. Flat config is mandatory; no support for .eslintrc. ↓

fix Migrate to ESLint 9 flat config. See ESLint migration guide.

deprecated The canonical/ava, canonical/mocha, and canonical/jest configs may be dropped in future versions in favor of vitest. ↓

fix Use canonical/vitest if possible, or copy the rules into your own config.

Install

npm install eslint-config-canonical

yarn add eslint-config-canonical

pnpm add eslint-config-canonical

Imports

auto

wrong

const auto = require('eslint-config-canonical/auto');

correct

import auto from 'eslint-config-canonical/auto';

ESM-only since v47. No CJS support. Use default import for rulesets.

configs
wrong
```
const configs = require('eslint-config-canonical');
```
correct
```
import * as configs from 'eslint-config-canonical';
```
ESM-only. Named exports are deprecated; use specific ruleset paths like 'eslint-config-canonical/react' instead.

typescript

wrong

import { typescript } from 'eslint-config-canonical';

correct

import typescript from 'eslint-config-canonical/typescript';

Each ruleset is a default export from its own file. Use the path /typescript, /react, etc.

Quickstart

Shows how to use the auto ruleset with typescript-eslint in an ESLint flat config file.

// eslint.config.ts
import auto from 'eslint-config-canonical/auto';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  auto,
  // Add custom overrides or other configs
  {
    rules: {
      'canonical/filename-match-regex': 'off', // Example override
    },
  },
);