Nightly Pocket Measurement

    eslint-kit
    TypeScript icon, indicating that this package has built-in type declarations

    5.7.0 • Public • Published

    ESLint Kit

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


    eslint-kit CI Status License npm stars

    Before you start

    The README on main branch can contain some unreleased changes.

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

    Navigation

    Why?

    • Most configs contain too common rules inside, so you need to do a lot of things to finalize them for your project
    • The other configs are bound to specific stack/technology, so it's hard to extend them in a way you're like
    • Sometimes, configs use formatting rules. Formatting is not the ESLint's job, so it's a high chance to get the conflict someday
    • Together, above means that most likely you'll need a different ESLint config for each of your project
    • You may often need to install a lot of dependencies: eslint, plugins, configs, parser, etc.
    • You may often face the problems with eslint/parser/plugin/config versions. It takes time to find the issue and solution.

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

    You can select presets by using configure function in your .eslintrc.js 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 package contains all the dependencies you might need. The only exception is eslint - it 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
    

    Learn more about eslint-kit-cli

    Manual installation

    NPM:

    npm install -D eslint-kit eslint

    Yarn:

    yarn add -D eslint-kit eslint

    Note: You need ^8.16.0 version of ESLint

    After installing, add the .eslintrc.js 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) Mode
      // See "Linting Modes" section for more info 
      mode: 'default',
    
      // presets
      presets: [],
    
      // (optional) Custom eslint config
      // It gets merged with presets at the end
      extend: { rules: { /* ... */ } }
    })

    Presets

    Common

    Imports
    • Enables import and simple-import-sort plugins
    • Enables alias support for jsconfig and tsconfig
    • Configures file extensions depending on used presets
    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'
          }
        })
      ]
    })

    Under the hood, we use eslint-plugin-simple-import-sort. It provides an option to override sorting groups - check out this section in their README.

    This is the default groups values used by eslint-kit:

    [
      // 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
      ['^\\.'],
    ]

    To define your own groups, just pass it inside using sort.groups.

    TypeScript
    • Changes parser to @typescript-eslint/parser
    • Allows the usage of .ts and .tsx extensions
    • Adds some TypeScript specific rules (for TS files)
    • Replaces some default ESLint rules with their TypeScript analogues (for TS files)
    configure({
      presets: [
        presets.typescript({
          // (optional) Project's root
          root: './',
    
          // (optional) A path to tsconfig file
          tsconfig: 'tsconfig.json'
        })
      ]
    })
    Prettier
    • Enables the rule prettier/prettier from Prettier ESLint plugin
    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
          // ...
        })
      ]
    })

    The recommended Prettier config:

    {
      "semi": false,
      "singleQuote": true,
      "tabWidth": 2,
      "quoteProps": "consistent"
    }
    Node
    • Enables node environment
    configure({
      presets: [presets.node()]
    })

    Frameworks

    React
    • Adds some React and React Hooks rules
    • Enables browser environment and jsx ecma feature
    configure({
      presets: [
        presets.react({
          // (optional) Allows to specify React version
          version: 'detect',
          // (optional) Allows using JSX without importing `React`
          newJSXTransform: false
        })
      ]
    })
    Vue
    • Adds vue plugin
    • Changes parser to vue-eslint-parser
    • Detects installed vue version and enables /recommended rules for it
    • Enables @typescript-eslint/parser for <script> blocks when typescript preset is used
    • Enables browser environment and jsx ecma feature
    • Allows export default

    You still need to setup your editor / IDE to lint .vue files. You can use this guide from Vue documentation.

    configure({
      presets: [
        presets.vue({
          // (optional) Allows to specify Vue version
          version: 'detect'
        })
      ]
    })
    Solid.js
    • Adds solid plugin and enables /recommended rules
    • Enables /typescript rules when typescript preset is active
    configure({
      presets: [presets.solidJs()]
    })
    Svelte
    • Adds svelte3 plugin and configures it
    • Enables some TypeScript settings when typescript preset is active

    You still need to setup your editor / IDE to lint .svelte files. You can use this guide from svelte3 plugin repo.

    configure({
      presets: [
        presets.svelte({
          // (optional) Disable type checking for .svelte files
          noTypeCheck: true
        })
      ]
    })
    Next.js
    • Enables @next/eslint-plugin-next plugin rules
    • Enables new JSX transform support
    • Allows the usage of export default

    nextJs preset doesn't provide React rules, so don't forget to add react preset too. You may omit newJSXTransform, since it's already included in nextJs.

    configure({
      presets: [presets.react(), presets.nextJs()]
    })
    Remix
    • Enables new JSX transform support
    • Allows the usage of export default

    remix preset doesn't provide React rules, so don't forget to add react preset too. You may omit newJSXTransform, since it's already included in remix.

    configure({
      presets: [presets.react(), presets.remix()]
    })

    Libraries

    Effector
    • Adds effector plugin and enables /recommended, /scope, and /react rules
    configure({
      presets: [
        presets.effector({
          // (optional) Enables /future rules
          onlySample: false
        })
      ]
    })

    Linting Modes

    const { configure, presets } = require('eslint-kit')
    
    module.exports = configure({
      mode: 'decrease-level',
      /* ... */
    })

    Linting Modes are useful when you want to set similar behavior to a large number of rules.

    default

    Do not transform rule levels. This is the default value.

    decrease-level

    Transform error to warn, and warn to off.

    It's useful for an incremental adoption: you can focus on fixing only critical issues first.

    only-errors

    Transform warn to error.

    It's useful when you want to completely prevent any warnings to get into your main branch.

    only-warns

    Transform error to warn.

    I have no idea when this may be useful, but ok.

    disable-warns

    Transform warn to off.

    I have no idea when this may be useful, but ok.

    Common issues

    Q: ESLint ignores my .eslintrc.js, why?
    A: It's a regular issue with tools like @vue/cli and create-react-app. Check package.json and remove eslintConfig if you find it. Otherwise, try to restart your editor.

    Q: ESLint couldn't determine the plugin "foo" uniquely
    A: Most likely your .eslintrc.js is located inside some nested project directory, so that you have eslint package installed in the high-level node_modules. You can try setting extend.root to true like in the example below:

    configure({
      presets: [/* ... */],
      extend: {
        root: true
      }
    })

    Q: In my monorepo, ESLint complains about tsconfig.json (or another file) location. How can I fix it?
    A: Just set up root option inside your nested package (workspace) .eslintrc.js like in the example below:

    configure({
      root: __dirname,
      presets: [/* ... */]
    })

    Q: I get some another error when using eslint-kit in monorepo
    A: We didn't test monorepos much. They often have different issues with eslint and plugins resolving. And we also don't guarantee that your aliases settings will work in monorepo.

    Setting up editors

    VSCode

    Install ESLint VSCode extension:

    CleanShot 2022-05-22 at 02 12 33@2x

    Next, select from the following and click on it:

    Using a keybind

    Click on Settings icon:

    Opening settings menu

    Select "Keyboard shortcuts"

    Selecting keybind settings

    Type "eslint" and click on "edit" button:

    Adding a keybind

    Finally, choose the keybind you like.

    Linting on file save

    Click on Settings icon:

    Opening settings menu

    Select "Settings"

    Selecting settings

    Switch to text mode:

    Switching to text mode

    Finally, add the following and save:

    {
      "eslint.validate": [
        "javascript",
        "javascriptreact",
        "typescript",
        "typescriptreact",
      ],
      "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true,
      },
    }

    Contributing

    1. Fork this repo
    2. Switch to new branch, it should start with feat/, fix/, docs/, refactor/, and etc., depending on the changes you want to propose
    3. Make changes
    4. Create a Pull Request into this repo's main branch
    5. When the checks is done and review is passed, I'll merge it into main and it will create a new record in the changelog. Then, when release is finally ready, your changes will be released.

    Maintenance

    The dev branch is main - any developer changes is merged in there. Also, there is a release branch. It always contains the actual published release source code and tag.

    All changes is made using Pull Requests - push is forbidden. PR can be merged only after successfull test-and-build workflow checks.

    When PR is merged, release-drafter workflow creates/updates a draft release. The changelog is built from the merged branch scope (feat, fix, etc) and PR title. When release is ready - we publish the draft.

    Then, the release workflow handles everything:

    1. We run tests and build a package
    2. Then, we merge release tag into the release branch
    3. After, we restore build artifacts and publish it to NPM

    Also, this repo has Renovate bot set up to auto-update typescript preset dependencies (they change frequently). The bot creates a PR into main branch and automatically merges it after successful checks.

    Keywords

    none

    Install

    npm i eslint-kit

    DownloadsWeekly Downloads

    146

    Version

    5.7.0

    License

    MIT

    Unpacked Size

    119 kB

    Total Files

    6

    Last publish

    Collaborators

    • risenforces