✨ All-in-one solution for configuring ESLint in all of your projects ✨

Before you start

The README on main branch can contain some unreleased changes.

Go to release/latest branch to see the actual README for the latest version from NPM.

Previous releases

• v10.x.x
• v9.x.x
• v8.x.x
• v7.x.x

Navigation

• Why?
• Quick installation
• Manual installation
• configure API
• Presets
  • Common
  • Frameworks
  • Libraries
• Extends
• Allow Debug
• Linting Modes
• Common issues
• Setting up editors
  • VSCode
• Contributing
• Maintenance

Why?

• Most configs contain too common rules inside, so you need to do a lot of things to finalize them for your project.
• You have to update config dependencies manually.
• The other configs are bound to a specific stack/technology, so it's hard to extend them in a way that you like.
• Sometimes, configs use formatting rules. Formatting is not ESLint's job, so there's a high chance to get into a conflict someday.
• Together, the above means that most likely you'll need a different ESLint config for each of your projects.
• You may often need to install a lot of dependencies: eslint, prettier, plugins, configs, parser, etc.
• You may often face problems with eslint/parser/plugin/config versions. It takes time to find the issue and solution.
• The average ESLint config UX is poor - for example, when using no-console rule, you will get warnings during the development. This kind of checks is useful when linting code for the production (CI environment, precommit hooks), but useless in development. ESLint Kit has allowDebug option to solve this problem.

ESLint Kit is solving all these problems by providing many small presets, each performing a specific task.

You can select presets by using configure function in your .eslintrc.cjs file:

const { configure, presets } = require('eslint-kit')

module.exports = configure({
  mode: 'only-errors',
  presets: [
    presets.imports(),
    presets.typescript(),
    presets.prettier(),
    presets.node(),
    presets.react({ version: '18.0' }),
  ],
  extend: {
    rules: {
      'some-rule': 'off'
    }
  }
})

eslint-kit dependencies are automatically updated. The configs are covered with tests, and each package update is tested. Broken plugins/rules/configs will not be deployed and will stuck at the review process, waiting for the fix by a developers.

eslint-kit package contains all the dependencies you might need. The only exception are eslint and prettier - they should be installed separately to work properly (executing yarn eslint and so on).

The ESLint Kit presets try to contain only the best-practice rules to make overwriting as rare as possible. But you can still easily override them by using extend property.

Quick installation

npx eslint-kit-cli@latest

Or if you want to use exactly 11 version of eslint-kit:

npx eslint-kit-cli@^11

Learn more about eslint-kit-cli

Manual installation

NPM:

npm install -D eslint-kit@^11.0.0 eslint@^8.57.0 prettier@^3.0.0

Yarn:

yarn add -D eslint-kit@^11.0.0 eslint@^8.57.0 prettier@^3.0.0

After installing, add the .eslintrc.cjs file in your project root:

const { configure, presets } = require('eslint-kit')

module.exports = configure({
  presets: [],
})

Now, just select the presets you need. The full information about them is located in Presets section.

You can also set up your editor if you haven't already.

configure API

configure({
  // (optional) Project root
  root: __dirname,

  // (optional) Base ESLint Config to extend from
  // May be used in monorepos to declare shared ESLint Kit options for all packages
  // See "Extends" section for more info
  extends: '../../base.eslintrc.cjs',
  // Also accepts ESLint Config object, but only if it was created using ESLint Kit
  extends: require(path.resolve(__dirname, '../../base.eslintrc.cjs')),
  
  // (optional) Allow debug
  // Very good option for development
  // See "Allow Debug" section for more info
  allowDebug: false,

  // (optional) Mode
  // See "Linting Modes" section for more info 
  mode: 'default',

  // (optional) ESLint Kit presets
  presets: [],

  // (optional) Custom eslint config
  // It gets merged with presets at the end
  extend: { rules: { /* ... */ } }
})

Presets

Common

configure({
  presets: [
    presets.imports({
      // (optional) Imports sort settings
      sort: {
        // (optional) Add newline between import groups
        newline: false,

        // (optional) Define groups for sorting (see below)
        groups: [/* ... */]
      },

      // (optional) Alias settings
      alias: {
        // (optional) Base path for all aliases
        // Defaults to './'
        root: './src',

        // (optional) Aliases
        // Defaults to empty object
        paths: { '@app': './' },

        // (optional) A custom path to jsconfig
        // Defaults to jsconfig.json
        jsconfig: 'jsconfig.json'
      }
    })
  ]
})

[
  // side effects
  ['^\\u0000'],

  // node.js libraries and scoped libraries
  ['^(child_process|crypto|events|fs|http|https|os|path)(/.*)?$', '^@?\\w'],

  // common aliases (@app, @root, @/, ~/) and anything not matched
  ['^@app', '^@root', '^~', '^'],

  // relative imports
  ['^\\.'],
]

configure({
  presets: [
    presets.typescript({
      // (optional) Project's root
      root: './',

      // (optional) A path to tsconfig file
      tsconfig: 'tsconfig.json',

      // (optional) Enforce using `type` insead of `interface`
      // Default to `false` in v11, will become `true` in v12, and will be removed in v13
      // ESLint Kit CLI will set `true` on bootstrap
      enforceUsingType: false,
    })
  ]
})

configure({
  presets: [
    /*
     * Optionally, you can pass the Prettier config
     * Note: it will merge and override any options set with .prettierrc files
     */
    presets.prettier({
      semi: false,
      singleQuote: true
      // ...
    })
  ]
})

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "quoteProps": "consistent"
}

configure({
  presets: [presets.node()]
})

Frameworks

configure({
  presets: [
    presets.react({
      // (optional) Allows to specify React version
      version: 'detect',
      // (optional) Allows using JSX without importing `React`
      newJSXTransform: false
    })
  ]
})