Skip to content

Commit ffa9354

Browse files
committed
chore: update docs
1 parent ba4cd6a commit ffa9354

File tree

1 file changed

+230
-51
lines changed

1 file changed

+230
-51
lines changed

README.md

Lines changed: 230 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -6,35 +6,34 @@
66

77
## Feature
88

9-
- Single quotes, no semi
10-
- Auto fix for formatting (aimed to be used standalone **without** Prettier)
11-
- Designed to work with TypeScript, Vue out-of-box
12-
- Lint also for json, yaml, markdown
13-
- Sorted imports, dangling commas
14-
- Reasonable defaults, best practices, only one-line of config
9+
- ✨ Single quotes, no semi
10+
- 🛠️ Auto fix for formatting (aimed to be used standalone **without** Prettier)
11+
- 🎯 Designed to work with TypeScript, Vue out-of-box
12+
- 🔍 Lints also for json, yaml, markdown
13+
- 🧩 Sorted imports, dangling commas
14+
- 🏆 Reasonable defaults, best practices, only one-line of config
15+
- 🚀 [ESLint Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new), compose easily!
16+
- 🎨 Using [ESLint Stylistic](https://github.com/eslint-stylistic/eslint-stylistic)
17+
- 📖 **Style principle**: Minimal for reading, stable for diff, consistent
1518

1619
## Usage
1720

1821
### Install
1922

2023
```bash
21-
pnpm add -D eslint @coderwyd/eslint-config # JavaScript, TypeScript and Vue 3
22-
# Or yarn add eslint @coderwyd/eslint-config -D / npm install eslint @coderwyd/eslint-config -D
23-
pnpm add -D @coderwyd/eslint-config-basic # JavaScript only
24-
pnpm add -D @coderwyd/eslint-config-ts # JavaScript and TypeScript
25-
pnpm add -D @coderwyd/eslint-config-react # JavaScript, TypeScript and React
26-
pnpm add -D @coderwyd/eslint-config-vue # JavaScript, TypeScript and Vue 3
24+
pnpm i -D eslint @coderwyd/eslint-config
2725
```
2826

29-
### Config `.eslintrc`
27+
### Create config file
3028

31-
```json
32-
{
33-
"extends": "@coderwyd"
34-
}
29+
```js
30+
// eslint.config.js
31+
import coderwyd from '@coderwyd/eslint-config'
32+
33+
export default coderwyd()
3534
```
3635

37-
> You don't need `.eslintignore` normally as it has been provided by the preset.
36+
> Note that `.eslintignore` no longer works in Flat config, see [customization](#customization) for more details.
3837
3938
### Add script for package.json
4039

@@ -49,40 +48,237 @@ For example:
4948
}
5049
```
5150

52-
### VS Code support (auto fix)
51+
## VS Code support (auto fix)
52+
53+
Install [VS Code ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
5354

54-
Add the following settings to your `settings.json`:
55+
Add the following settings to your `.vscode/settings.json`:
5556

5657
```jsonc
5758
{
59+
// Enable the ESlint flat config support
60+
"eslint.experimental.useFlatConfig": true,
61+
62+
// Disable the default formatter, use eslint instead
5863
"prettier.enable": false,
5964
"editor.formatOnSave": false,
65+
66+
// Auto fix
6067
"editor.codeActionsOnSave": {
6168
"source.fixAll.eslint": true,
6269
"source.organizeImports": false
6370
},
6471

65-
// The following is optional.
66-
// It's better to put under project setting `.vscode/settings.json`
67-
// to avoid conflicts with working with different eslint configs
68-
// that does not support all formats.
69-
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact", "vue", "html", "markdown", "json", "jsonc", "yaml"]
72+
// Silent the stylistic rules in you IDE, but still auto fix them
73+
"eslint.rules.customizations": [
74+
{ "rule": "style/*", "severity": "off" },
75+
{ "rule": "*-indent", "severity": "off" },
76+
{ "rule": "*-spacing", "severity": "off" },
77+
{ "rule": "*-spaces", "severity": "off" },
78+
{ "rule": "*-order", "severity": "off" },
79+
{ "rule": "*-dangle", "severity": "off" },
80+
{ "rule": "*-newline", "severity": "off" },
81+
{ "rule": "*quotes", "severity": "off" },
82+
{ "rule": "*semi", "severity": "off" }
83+
],
84+
85+
// Enable eslint for all supported languages
86+
"eslint.validate": [
87+
"javascript",
88+
"javascriptreact",
89+
"typescript",
90+
"typescriptreact",
91+
"vue",
92+
"html",
93+
"markdown",
94+
"json",
95+
"jsonc",
96+
"yaml"
97+
]
7098
}
7199
```
72100

73-
### TypeScript Aware Rules
101+
## Customization
74102

75-
Type aware rules are enabled when a `tsconfig.eslint.json` is found in the project root, which will introduce some stricter rules into your project. If you want to enable it while have no `tsconfig.eslint.json` in the project root, you can change tsconfig name by modifying `ESLINT_TSCONFIG` env.
103+
Since v1.0, we migrated to [ESLint Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new), provides a much better organization and composition.
104+
105+
Normally you only need to import the `coderwyd` preset:
76106

77107
```js
78-
// .eslintrc.js
79-
const process = require('node:process')
108+
// eslint.config.js
109+
import coderwyd from '@coderwyd/eslint-config'
110+
111+
export default coderwyd()
112+
```
80113

81-
process.env.ESLINT_TSCONFIG = 'tsconfig.json'
114+
And that's it! Or you can configure each integration individually, for example:
82115

83-
module.exports = {
84-
extends: '@coderwyd',
85-
}
116+
```js
117+
// eslint.config.js
118+
import coderwyd from '@coderwyd/eslint-config'
119+
120+
export default coderwyd({
121+
stylistic: true, // enable stylistic formatting rules
122+
typescript: true,
123+
vue: true,
124+
jsonc: false, // disable jsonc support
125+
yaml: false,
126+
127+
// `.eslintignore` is no longer supported in Flat config, use `ignores` instead
128+
ignores: [
129+
'./fixtures',
130+
// ...globs
131+
]
132+
})
133+
```
134+
135+
The `coderwyd` factory functions also accepts arbitrary numbers of constom configs overrides:
136+
137+
```js
138+
// eslint.config.js
139+
import coderwyd from '@coderwyd/eslint-config'
140+
141+
export default coderwyd(
142+
{
143+
// Configures for coderwyd's config
144+
},
145+
146+
// From the second arguments they are ESLint Flat Configs
147+
// you can have multiple configs
148+
{
149+
files: ['**/*.ts'],
150+
rules: {},
151+
},
152+
{
153+
rules: {},
154+
},
155+
)
156+
```
157+
158+
Going more advanced, you can also import the very fine-grained configs and compose them as you wish:
159+
160+
```js
161+
// eslint.config.js
162+
import {
163+
astro,
164+
comments,
165+
ignores,
166+
imports,
167+
javascript,
168+
jsdoc,
169+
jsonc,
170+
markdown,
171+
node,
172+
react,
173+
sortPackageJson,
174+
sortTsconfig,
175+
stylistic,
176+
typescript,
177+
unicorn,
178+
vue,
179+
yml,
180+
} from '@coderwyd/eslint-config'
181+
182+
export default [
183+
...astro(),
184+
...react(),
185+
...ignores(),
186+
...javascript(),
187+
...comments(),
188+
...node(),
189+
...jsdoc(),
190+
...imports(),
191+
...unicorn(),
192+
...typescript(),
193+
...stylistic(),
194+
...vue(),
195+
...jsonc(),
196+
...yml(),
197+
...markdown(),
198+
]
199+
```
200+
201+
Check out the [configs](https://github.com/coderwyd/eslint-config/blob/main/src/configs) and [factory](https://github.com/coderwyd/eslint-config/blob/main/src/factory.ts) for more details.
202+
203+
## Plugins Renaming
204+
205+
Since flat config requires us to explicitly provide the plugin names (instead of mandatory convention from npm package name), we renamed some plugins to make overall scope more consistent and easier to write.
206+
207+
| New Prefix | Original Prefix | Source Plugin |
208+
| --- | --- | --- |
209+
| `import/*` | `i/*` | [eslint-plugin-i](https://github.com/un-es/eslint-plugin-i) |
210+
| `node/*` | `n/*` | [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n) |
211+
| `yaml/*` | `yml/*` | [eslint-plugin-yml](https://github.com/ota-meshi/eslint-plugin-yml) |
212+
| `ts/*` | `@typescript-eslint/*` | [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint) |
213+
| `style/*` | `@stylistic/*` | [@stylistic/eslint-plugin](https://github.com/eslint-stylistic/eslint-stylistic) |
214+
215+
When you want to overrides rules, or disable them inline, you need to update to the new prefix:
216+
217+
```diff
218+
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
219+
+// eslint-disable-next-line ts/consistent-type-definitions
220+
type foo = { bar: 2 }
221+
```
222+
223+
### Rules Overrides
224+
225+
Certain rules would only be enabled in specific files, for example, `ts/*` rules would only be enabled in `.ts` files and `vue/*` rules would only be enabled in `.vue` files. If you want to override the rules, you need to specify the file extension:
226+
227+
```js
228+
// eslint.config.js
229+
import coderwyd from '@coderwyd/eslint-config'
230+
231+
export default coderwyd(
232+
{ vue: true, typescript: true },
233+
{
234+
// Remember to specify the file glob here, otherwise it might cause the vue plugin to handle non-vue files
235+
files: ['**/*.vue'],
236+
rules: {
237+
'vue/operator-linebreak': ['error', 'before'],
238+
},
239+
},
240+
{
241+
// Without `files`, they are general rules for all files
242+
rules: {
243+
'style/semi': ['error', 'never'],
244+
},
245+
}
246+
)
247+
```
248+
249+
We also provided an `overrides` options to make it easier:
250+
251+
```js
252+
// eslint.config.js
253+
import coderwyd from '@coderwyd/eslint-config'
254+
255+
export default coderwyd({
256+
overrides: {
257+
vue: {
258+
'vue/operator-linebreak': ['error', 'before'],
259+
},
260+
typescript: {
261+
'ts/consistent-type-definitions': ['error', 'interface'],
262+
},
263+
yaml: {},
264+
// ...
265+
}
266+
})
267+
```
268+
269+
### Type Aware Rules
270+
271+
You can optionally enable the [type aware rules](https://typescript-eslint.io/linting/typed-linting/) by passing the options object to the `typescript` config:
272+
273+
```js
274+
// eslint.config.js
275+
import coderwyd from '@coderwyd/eslint-config'
276+
277+
export default coderwyd({
278+
typescript: {
279+
tsconfigPath: 'tsconfig.json',
280+
},
281+
})
86282
```
87283

88284
### Lint Staged
@@ -106,27 +302,10 @@ and then
106302
npm i -D lint-staged simple-git-hooks
107303
```
108304

109-
## FAQ
110-
111-
### Customization rules
112-
113-
add you like rules to your .eslintrc file.
114-
115-
<!-- eslint-skip -->
116-
117-
```jsonc
118-
{
119-
"extends": "@coderwyd",
120-
"rules": {
121-
// your rules...
122-
}
123-
}
124-
```
125-
126305
## Thanks
127306

128307
This project is based on [@antfu/eslint-config](https://github.com/antfu/eslint-config)
129308

130309
## License
131310

132-
[MIT](./LICENSE) License &copy; 2019-PRESENT [Donny Wang](https://github.com/coderwyd)
311+
[MIT](./LICENSE) License &copy; 2023-PRESENT [Donny Wang](https://github.com/coderwyd)

0 commit comments

Comments
 (0)