Skip to content

Commit 51893e6

Browse files
octogonzoctogonz
committed
Add README.md docs
1 parent ac50215 commit 51893e6

File tree

3 files changed

+134
-4
lines changed

3 files changed

+134
-4
lines changed

‎stack/eslint-config/LICENSE‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
@rushstack/eslint-config
2+
3+
Copyright (c) Microsoft Corporation. All rights reserved.
4+
5+
MIT License
6+
7+
Permission is hereby granted, free of charge, to any person obtaining
8+
a copy of this software and associated documentation files (the
9+
"Software"), to deal in the Software without restriction, including
10+
without limitation the rights to use, copy, modify, merge, publish,
11+
distribute, sublicense, and/or sell copies of the Software, and to
12+
permit persons to whom the Software is furnished to do so, subject to
13+
the following conditions:
14+
15+
The above copyright notice and this permission notice shall be
16+
included in all copies or substantial portions of the Software.
17+
18+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
22+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
23+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
24+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎stack/eslint-config/README.md‎

Lines changed: 105 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,106 @@
1-
# @microsoft/eslint-config-scalable-ts
1+
# @rushstack/eslint-config
22

3-
This package contains a base set of rules for scalable TypeScript projects.
3+
A TypeScript ESLint ruleset designed for large teams and projects.
4+
5+
## Philosophy
6+
7+
When you work in a small repo, you spend most of your time writing code. You know what each file does. You want lint
8+
rules that keep things concise and won't slow you down. That's the situation for the 99% of open source projects
9+
that shape popular coding conventions.
10+
11+
But as your organization scales up, things may change. People come and go. Projects frequently get handed off between
12+
teams. Every day, you find yourself working with files that you've never seen before, created by strangers whom
13+
you may never meet. It's annoying to constantly come across inconsistent styles. It can be frustrating to decipher
14+
expressions that seem to require a TypeScript Ph.D. -- especially for newcomers and junior contributors. When
15+
refactoring in bulk, you may edit lots of files without reading them very carefully. In short, the linting needs
16+
reflect different priorities:
17+
18+
**Small scale:** We can assume developers are *familiar* with the project. We want code to be *easy to write*.
19+
20+
**Large scale:** Developers are generally *unfamiliar* with projects. Code must be *easy to read*. If not,
21+
there's a risk of fragmentation, duplication of efforts, and costly rewrites.
22+
23+
Welcome to the world of [Rush Stack](https://rushstack.io/)! The `@rushstack/eslint-config` package was specifically
24+
designed around the the requirements of large teams and projects.
25+
26+
27+
## Implementation
28+
29+
- **Monorepo friendly:** The `@rushstack/eslint-config` package has direct dependencies on all the ESLint plugins
30+
that it needs. This avoids encumbering each consuming project with a bunch of peer dependencies. It also ensures
31+
that the installed plugin versions were tested for compatibility.
32+
33+
- **Explicit:** The ruleset does not "extend" configs from other ESLint packages. This avoids worrying about
34+
precedence issues due to import order. It also eliminates confusion caused by settings overriding/undoing settings
35+
from another file. The [index.js](./index.js) file is a centralized, complete inventory of all rules.
36+
37+
- **Battle tested:** The `@rushstack/eslint-config` rules have been vetted on large production monorepos.
38+
The [index.js](./index.js) file includes code comments explaining the rationale behind each rule.
39+
40+
- **Minimal configuration:** Rather than providing opt-in entry points for different setups, we've rolled most of
41+
the rules into a single entry point. When you have hundreds of projects in a monorepo, a unified ruleset avoids
42+
having to maintain custom **.eslintrc.js** configs for each project. The extra cost for applying irrelevant
43+
ESLint rules turns out to be negligible in practice.
44+
45+
- **Designed for Prettier:** The `@rushstack/eslint-config` ruleset is designed to be used with
46+
the [Prettier](https://prettier.io/) code formatter. This separation of workflows avoids hassling developers with
47+
lint "errors" for frivolous issues like spaces and commas. Instead, those issues get fixed automatically whenever
48+
you save or commit a file. Prettier also avoids frivolous debates -- its defaults have already been debated
49+
at length and adopted by a sizeable community. No need to reinvent the wheel!
50+
51+
52+
## Usage
53+
54+
To install the package, do this:
55+
56+
```sh
57+
$ cd your-project-folder
58+
$ npm install --save-dev eslint
59+
$ npm install --save-dev typescript
60+
$ npm install --save-dev @rushstack/eslint-config
61+
```
62+
63+
Next, create an **.eslintrc** config file that provides the NodeJS `__dirname` context:
64+
65+
**.eslintrc**
66+
```ts
67+
// This is a workaround for https://github.com/eslint/eslint/issues/3458
68+
require("@rushstack/eslint-config/patch-eslint6");
69+
70+
module.exports = {
71+
extends: [ "@rushstack/eslint-config" ],
72+
parserOptions: { tsconfigRootDir: __dirname }
73+
};
74+
```
75+
76+
For projects using React, you'll need a **tsconfig.json** with `"jsx": "react"`. You also need to configure your
77+
React version, which the lint rules use to determine deprecated APIs. Specify it like this:
78+
79+
**.eslintrc**
80+
```ts
81+
// This is a workaround for https://github.com/eslint/eslint/issues/3458
82+
require("@rushstack/eslint-config/patch-eslint6");
83+
84+
module.exports = {
85+
extends: [
86+
"@rushstack/eslint-config",
87+
"@rushstack/eslint-config/react"
88+
],
89+
parserOptions: { tsconfigRootDir: __dirname },
90+
91+
settings: {
92+
react: {
93+
"version": "16.9"
94+
}
95+
}
96+
};
97+
```
98+
99+
The `@rushstack/eslint-config` ruleset is intended to be used with the Prettier code formatter. For instructions
100+
on setting that up, please refer to the [Prettier docs](https://prettier.io/docs/en/index.html).
101+
102+
103+
## Learn more
104+
105+
This package is part of the Rush Stack project. Please visit [https://rushstack.io/](https://rushstack.io/)
106+
for more guidance as well as [help resources](https://rushstack.io/pages/help/support/).

‎stack/eslint-config/package.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,22 @@
11
{
22
"name": "@rushstack/eslint-config",
33
"version": "0.4.0",
4-
"description": "Base set of ESLint rules for scalable TypeScript projects.",
4+
"description": "A TypeScript ESLint ruleset designed for large teams and projects",
55
"license": "MIT",
66
"repository": {
77
"url": "https://github.com/microsoft/rushstack/tree/master/stack/eslint-config"
88
},
9+
"homepage": "https://rushstack.io",
910
"scripts": {
1011
"build": ""
1112
},
1213
"keywords": [
1314
"eslint",
1415
"eslint-config",
16+
"monorepo",
1517
"rush",
16-
"rushstack",
18+
"scalable",
19+
"scale",
1720
"typescript"
1821
],
1922
"peerDependencies": {

0 commit comments

Comments
 (0)