eslint-config

@rushstack/eslint-config

A TypeScript ESLint ruleset designed for large teams and projects.

Philosophy

When you work in a small repo, you spend most of your time writing code. You know what each file does. You want lint rules that keep things concise and won't slow you down. That's the situation for the 99% of open source projects that shape popular coding conventions.

But as your organization scales up, things may change. People come and go. Projects frequently get handed off between teams. Every day, you find yourself working with files that you've never seen before, created by strangers whom you may never meet. It's annoying to constantly come across inconsistent styles. It can be frustrating to decipher expressions that seem to require a TypeScript Ph.D. -- especially for newcomers and junior contributors. When refactoring in bulk, you may edit lots of files without reading them very carefully. In short, the linting needs reflect different priorities:

Small scale: We can assume developers are familiar with the project. We want code to be easy to write.

Large scale: Developers are generally unfamiliar with projects. Code must be easy to read. If not, there's a risk of fragmentation, duplication of efforts, and costly rewrites.

Welcome to the world of Rush Stack! The @rushstack/eslint-config package was specifically designed around the the requirements of large teams and projects.

Implementation

• Monorepo friendly: The @rushstack/eslint-config package has direct dependencies on all the ESLint plugins that it needs. This avoids encumbering each consuming project with a bunch of peer dependencies. It also ensures that the installed plugin versions were tested for compatibility.

• Explicit: The ruleset does not "extend" configs from other ESLint packages. This avoids worrying about precedence issues due to import order. It also eliminates confusion caused by settings overriding/undoing settings from another file. The index.js file is a centralized, complete inventory of all rules.

• Battle tested: The @rushstack/eslint-config rules have been vetted on large production monorepos. The index.js file includes code comments explaining the rationale behind each rule.

• Minimal configuration: Rather than providing opt-in entry points for different setups, we've rolled most of the rules into a single entry point. When you have hundreds of projects in a monorepo, a unified ruleset avoids having to maintain custom .eslintrc.js configs for each project. The extra cost for applying irrelevant ESLint rules turns out to be negligible in practice.

• Designed for Prettier: The @rushstack/eslint-config ruleset is designed to be used with the Prettier code formatter. This separation of workflows avoids hassling developers with lint "errors" for frivolous issues like spaces and commas. Instead, those issues get fixed automatically whenever you save or commit a file. Prettier also avoids frivolous debates -- its defaults have already been debated at length and adopted by a sizeable community. No need to reinvent the wheel!

Usage

To install the package, do this:

$ cd your-project-folder
$ npm install --save-dev eslint
$ npm install --save-dev typescript
$ npm install --save-dev @rushstack/eslint-config

Next, create an .eslintrc config file that provides the NodeJS __dirname context:

.eslintrc

// This is a workaround for https://github.com/eslint/eslint/issues/3458
require("@rushstack/eslint-config/patch-eslint6");

module.exports = {
  extends: [ "@rushstack/eslint-config" ],
  parserOptions: { tsconfigRootDir: __dirname }
};

For projects using React, you'll need a tsconfig.json with "jsx": "react". You also need to configure your React version, which the lint rules use to determine deprecated APIs. Specify it like this:

.eslintrc

// This is a workaround for https://github.com/eslint/eslint/issues/3458
require("@rushstack/eslint-config/patch-eslint6");

module.exports = {
  extends: [
    "@rushstack/eslint-config",
    "@rushstack/eslint-config/react"
  ],
  parserOptions: { tsconfigRootDir: __dirname },

  settings: {
    react: {
      "version": "16.9"
    }
  }
};

The @rushstack/eslint-config ruleset is intended to be used with the Prettier code formatter. For instructions on setting that up, please refer to the Prettier docs.

Learn more

This package is part of the Rush Stack project. Please visit https://rushstack.io/ for more guidance as well as help resources.