Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: mention about name field in flat config #18252

Merged
merged 12 commits into from
Apr 4, 2024
26 changes: 26 additions & 0 deletions docs/src/use/configure/configuration-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ module.exports = [

Each configuration object contains all of the information ESLint needs to execute on a set of files. Each configuration object is made up of these properties:

* `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))
* `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.
* `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`.
* `languageOptions` - An object containing settings related to how JavaScript is configured for linting.
Expand Down Expand Up @@ -342,6 +343,31 @@ Here, the `js.configs.recommended` predefined configuration is applied first and

For more information on how to combine predefined configs with your preferences, please see [Combine Configs](combine-configs).

### Configuration Naming Conventions

The `name` property is optional, but it is recommended to provide a name for each configuration object, especially when you are creating shared configurations. The name is used in error messages and the config inspector to help identify which configuration object is being used.

The name should be descriptive of the configuration object's purpose and scoped with the configurations name or plugin name. Using `/` as the seperator. For example, if you are creating a configuration object for a plugin named `eslint-plugin-example`, you might add `name` to the configuration objects with the `example/` prefix:
antfu marked this conversation as resolved.
Show resolved Hide resolved

```js
export default {
configs: {
recommended: {
name: "example/recommended",
rules: {
"no-unused-vars": "warn"
}
},
Comment on lines +357 to +362
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would be the convention if the configuration is an array of configuration objects? Would it be the same name for all configuration objects?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point! I mentioned it here 8cccc58

Supposely the config inspector could have an indicator of duplicated names to help with that as well.

strict: {
name: "example/strict",
rules: {
"no-unused-vars": "error"
}
}
}
}
```

## Using a Shareable Configuration Package

A sharable configuration is an npm package that exports a configuration object or array. This package should be installed as a dependency in your project and then referenced from inside of your `eslint.config.js` file. For example, to use a shareable configuration named `eslint-config-example`, your configuration file would look like this:
Expand Down