Skip to content

Commit a59d0c0

Browse files
nzakasmdjermanovic
nzakas
and
mdjermanovic
authored
docs: Update docs for defineConfig (#19505)
* docs: Update docs for defineConfig * Update docs/src/extend/plugin-migration-flat-config.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/extend/languages.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/extend/plugins.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/extend/shareable-configs.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/extend/shareable-configs.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/extend/shareable-configs.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/extend/shareable-configs.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update docs/src/use/getting-started.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Fix last code example * Update packages/js/README.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update packages/js/README.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update packages/js/README.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> --------- Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
1 parent d46ff83 commit a59d0c0

9 files changed

Lines changed: 157 additions & 106 deletions

File tree

‎docs/src/extend/custom-processors.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -152,17 +152,19 @@ Example:
152152

153153
```js
154154
// eslint.config.js
155+
import { defineConfig } from "eslint/config";
155156
import example from "eslint-plugin-example";
156157
157-
export default [
158+
export default defineConfig([
158159
{
160+
files: ["**/*.txt"], // apply processor to text files
159161
plugins: {
160162
example
161163
},
162164
processor: "example/processor-name"
163165
},
164166
// ... other configs
165-
];
167+
]);
166168
```
167169

168170
In this example, the processor name is `"example/processor-name"`, and that's the value that will be used for serializing configurations.
@@ -175,14 +177,16 @@ Example:
175177

176178
```js
177179
// eslint.config.js
180+
import { defineConfig } from "eslint/config";
178181
import example from "eslint-plugin-example";
179182
180-
export default [
183+
export default defineConfig([
181184
{
185+
files: ["**/*.txt"],
182186
processor: example.processors["processor-name"]
183187
},
184188
// ... other configs
185-
];
189+
]);
186190
```
187191

188192
In this example, specifying `example.processors["processor-name"]` directly uses the processor's own `meta` object, which must be defined to ensure proper handling when the processor is not referenced through the plugin name.
@@ -197,16 +201,18 @@ In order to use a processor from a plugin in a configuration file, import the pl
197201

198202
```js
199203
// eslint.config.js
204+
import { defineConfig } from "eslint/config";
200205
import example from "eslint-plugin-example";
201206
202-
export default [
207+
export default defineConfig([
203208
{
209+
files: ["**/*.txt"],
204210
plugins: {
205211
example
206212
},
207213
processor: "example/processor-name"
208214
}
209-
];
215+
]);
210216
```
211217

212218
See [Specify a Processor](../use/configure/plugins#specify-a-processor) in the Plugin Configuration documentation for more details.

‎docs/src/extend/languages.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,16 +124,18 @@ In order to use a language from a plugin in a configuration file, import the plu
124124

125125
```js
126126
// eslint.config.js
127+
import { defineConfig } from "eslint/config";
127128
import example from "eslint-plugin-example";
128129

129-
export default [
130+
export default defineConfig([
130131
{
132+
files: ["**/*.my"],
131133
plugins: {
132134
example
133135
},
134136
language: "example/my"
135137
}
136-
];
138+
]);
137139
```
138140

139141
See [Specify a Language](../use/configure/plugins#specify-a-language) in the Plugin Configuration documentation for more details.

‎docs/src/extend/plugin-migration-flat-config.md‎

Lines changed: 24 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -114,16 +114,18 @@ module.exports = plugin;
114114
In order to use this renamed processor, you'll also need to manually specify it inside of a config, such as:
115115

116116
```js
117+
import { defineConfig } from "eslint/config";
117118
import example from "eslint-plugin-example";
118119

119-
export default [
120+
export default defineConfig([
120121
{
122+
files: ["**/*.md"],
121123
plugins: {
122124
example
123125
},
124126
processor: "example/markdown"
125127
}
126-
];
128+
]);
127129
```
128130

129131
You should update your plugin's documentation to advise your users if you have renamed a file extension-named processor.
@@ -185,20 +187,23 @@ module.exports = plugin;
185187
Your users can then use this exported config like this:
186188

187189
```js
190+
import { defineConfig } from "eslint/config";
188191
import example from "eslint-plugin-example";
189192

190-
export default [
193+
export default defineConfig([
191194

192-
// use recommended config
193-
example.configs.recommended,
194-
195-
// and provide your own overrides
195+
// use recommended config and provide your own overrides
196196
{
197+
files: ["**/*.js"],
198+
plugins: {
199+
example
200+
},
201+
extends: ["example/recommended"],
197202
rules: {
198203
"example/rule1": "warn"
199204
}
200205
}
201-
];
206+
]);
202207
```
203208

204209
If your config extends other configs, you can export an array:
@@ -223,19 +228,6 @@ module.exports = {
223228

224229
You should update your documentation so your plugin users know how to reference the exported configs.
225230

226-
If your exported config is an object, then your users can insert it directly into the config array; if your exported config is an array, then your users should use the spread operator (`...`) to insert the array's items into the config array.
227-
228-
Here's an example with both an object config and an array config:
229-
230-
```js
231-
import example from "eslint-plugin-example";
232-
233-
export default [
234-
example.configs.recommended, // Object, so don't spread
235-
...example.configs.extendedConfig, // Array, so needs spreading
236-
];
237-
```
238-
239231
For more information, see the [full documentation](https://eslint.org/docs/latest/extend/plugins#configs-in-plugins).
240232

241233
## Migrating Environments for Flat Config
@@ -295,22 +287,27 @@ module.exports = plugin;
295287
Your users can then use this exported config like this:
296288

297289
```js
290+
import { defineConfig } from "eslint/config";
298291
import example from "eslint-plugin-example";
299292

300-
export default [
293+
export default defineConfig([
294+
{
295+
files: ["**/tests/*.js"],
296+
plugins: {
297+
example
298+
},
301299

302-
// use the mocha globals
303-
example.configs.mocha,
300+
// use the mocha globals
301+
extends: ["example/mocha"],
304302

305-
// and provide your own overrides
306-
{
303+
// and provide your own overrides
307304
languageOptions: {
308305
globals: {
309306
it: "readonly"
310307
}
311308
}
312309
}
313-
];
310+
]);
314311
```
315312

316313
You should update your documentation so your plugin users know how to reference the exported configs.

‎docs/src/extend/plugins.md‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -145,9 +145,10 @@ In order to use a rule from a plugin in a configuration file, import the plugin
145145
146146
```js
147147
// eslint.config.js
148+
import { defineConfig } from "eslint/config";
148149
import example from "eslint-plugin-example";
149150

150-
export default [
151+
export default defineConfig([
151152
{
152153
plugins: {
153154
example
@@ -156,7 +157,7 @@ export default [
156157
"example/dollar-sign": "error"
157158
}
158159
}
159-
];
160+
]);
160161
```
161162
162163
::: warning
@@ -192,16 +193,18 @@ In order to use a processor from a plugin in a configuration file, import the pl
192193
193194
```js
194195
// eslint.config.js
196+
import { defineConfig } from "eslint/config";
195197
import example from "eslint-plugin-example";
196198

197-
export default [
199+
export default defineConfig([
198200
{
201+
files: ["**/*.txt"],
199202
plugins: {
200203
example
201204
},
202205
processor: "example/processor-name"
203206
}
204-
];
207+
]);
205208
```
206209
207210
### Configs in Plugins
@@ -257,15 +260,26 @@ module.exports = plugin;
257260
258261
This plugin exports a `recommended` config that is an array with one config object. When there is just one config object, you can also export just the object without an enclosing array.
259262
260-
In order to use a config from a plugin in a configuration file, import the plugin and access the config directly through the plugin object. Assuming the config is an array, use the spread operator to add it into the array returned from the configuration file, like this:
263+
::: tip
264+
Your plugin can export both current (flat config) and legacy (eslintrc) config objects in the `configs` key. When exporting legacy configs, we recommend prefixing the name with `"legacy-"` (for example, `"legacy-recommended"`) to make it clear how the config should be used.
265+
:::
266+
267+
In order to use a config from a plugin in a configuration file, import the plugin and use the `extends` key to reference the name of the config, like this:
261268
262269
```js
263270
// eslint.config.js
271+
import { defineConfig } from "eslint/config";
264272
import example from "eslint-plugin-example";
265273

266-
export default [
267-
...example.configs.recommended
268-
];
274+
export default defineConfig([
275+
{
276+
files: ["**/*.js"], // any patterns you want to apply the config to
277+
plugins: {
278+
example
279+
},
280+
extends: ["example/recommended"]
281+
}
282+
]);
269283
```
270284
271285
::: important

‎docs/src/extend/shareable-configs.md‎

Lines changed: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,19 @@ If your shareable config depends on a plugin or a custom parser, you should spec
6969

7070
## Using a Shareable Config
7171

72-
To use a shareable config, import the package inside of an `eslint.config.js` file and add it into the exported array, like this:
72+
To use a shareable config, import the package inside of an `eslint.config.js` file and add it into the exported array using `extends`, like this:
7373

7474
```js
7575
// eslint.config.js
76+
import { defineConfig } from "eslint/config";
7677
import myconfig from "eslint-config-myconfig";
7778

78-
export default [
79-
...myconfig
80-
];
79+
export default defineConfig([
80+
{
81+
files: ["**/*.js"],
82+
extends: [myconfig]
83+
}
84+
]);
8185
```
8286

8387
::: warning
@@ -90,18 +94,20 @@ You can override settings from the shareable config by adding them directly into
9094

9195
```js
9296
// eslint.config.js
97+
import { defineConfig } from "eslint/config";
9398
import myconfig from "eslint-config-myconfig";
9499

95-
export default [
96-
...myconfig,
97-
98-
// anything from here will override myconfig
100+
export default defineConfig([
99101
{
102+
files: ["**/*.js"],
103+
extends: [myconfig],
104+
105+
// anything from here will override myconfig
100106
rules: {
101107
"no-unused-vars": "warn"
102108
}
103109
}
104-
];
110+
]);
105111
```
106112

107113
## Sharing Multiple Configs
@@ -123,20 +129,21 @@ Then, assuming you're using the package name `eslint-config-myconfig`, you can a
123129

124130
```js
125131
// eslint.config.js
132+
import { defineConfig } from "eslint/config";
126133
import myconfig from "eslint-config-myconfig";
127134
import mySpecialConfig from "eslint-config-myconfig/my-special-config.js";
128135

129-
export default [
130-
...myconfig,
131-
mySpecialConfig,
132-
133-
// anything from here will override myconfig and mySpecialConfig
136+
export default defineConfig([
134137
{
138+
files: ["**/*.js"],
139+
extends: [myconfig, mySpecialConfig],
140+
141+
// anything from here will override myconfig
135142
rules: {
136143
"no-unused-vars": "warn"
137144
}
138145
}
139-
];
146+
]);
140147
```
141148

142149
::: important

‎docs/src/use/configure/configuration-files.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ Each configuration object contains all of the information ESLint needs to execut
6969
* `name` - A name for the configuration object. This is used in error messages and config inspector to help identify which configuration object is being used. ([Naming Convention](#configuration-naming-conventions))
7070
* `files` - An array of glob patterns indicating the files that the configuration object should apply to. If not specified, the configuration object applies to all files matched by any other configuration object.
7171
* `ignores` - An array of glob patterns indicating the files that the configuration object should not apply to. If not specified, the configuration object applies to all files matched by `files`. If `ignores` is used without any other keys in the configuration object, then the patterns act as [global ignores](#globally-ignoring-files-with-ignores) and it gets applied to every configuration object.
72+
* `extends` - An array of strings, configuration objects, or configuration arrays that contain additional configuration to apply.
7273
* `languageOptions` - An object containing settings related to how JavaScript is configured for linting.
7374
* `ecmaVersion` - The version of ECMAScript to support. May be any year (i.e., `2022`) or version (i.e., `5`). Set to `"latest"` for the most recent supported version. (default: `"latest"`)
7475
* `sourceType` - The type of JavaScript source code. Possible values are `"script"` for traditional script files, `"module"` for ECMAScript modules (ESM), and `"commonjs"` for CommonJS files. (default: `"module"` for `.js` and `.mjs` files; `"commonjs"` for `.cjs` files)
@@ -490,6 +491,7 @@ import { defineConfig } from "eslint/config";
490491

491492
export default defineConfig([
492493
{
494+
files: ["**/*.js"],
493495
plugins: {
494496
example: examplePlugin
495497
},
@@ -509,6 +511,7 @@ import { defineConfig } from "eslint/config";
509511

510512
export default defineConfig([
511513
{
514+
files: ["**/*.js"],
512515
plugins: {
513516
example: pluginExample
514517
},
@@ -519,6 +522,10 @@ export default defineConfig([
519522

520523
In this case, the configuration named `recommended` from `eslint-plugin-example` is accessed directly through the plugin object's `configs` property.
521524

525+
::: important
526+
It's recommended to always use a `files` key when you use the `extends` key to ensure that your configuration applies to the correct files. By omitting the `files` key, the extended configuration may end up applied to all files.
527+
:::
528+
522529
#### Using Predefined Configurations
523530

524531
ESLint has two predefined configurations for JavaScript:
@@ -535,6 +542,7 @@ import { defineConfig } from "eslint/config";
535542

536543
export default defineConfig([
537544
{
545+
files: ["**/*.js"],
538546
plugins: {
539547
js
540548
},
@@ -561,6 +569,7 @@ import { defineConfig } from "eslint/config";
561569

562570
export default defineConfig([
563571
{
572+
files: ["**/*.js"],
564573
extends: [exampleConfig],
565574
rules: {
566575
"no-unused-vars": "warn"

0 commit comments

Comments
 (0)