In ESLint 10's flat config, how do you load a plugin, and how are its rules then named in the `rules` object?
answer
- an object, not a list
- you import the plugin yourself
- the property name is the namespace
- namespace slash rule name
- string arrays were the eslintrc form
basics
~10 sImport the plugin in eslint.config.js and register it in a config object's plugins object under a namespace you choose; each of its rules is then configured as namespace/rule-name, for example crew/no-raw-dates.
solid answer
~40 sA plugin is a JavaScript object that can carry `rules`, `configs` (presets), `processors` and, since ESLint 9.7.0, `languages`. In flat config you `import` it in `eslint.config.js` and put it in a configuration object's `plugins` key: an object whose property name is the namespace and whose value is the plugin object, as in `plugins: { crew: crewPlugin }`. Every rule from that plugin is then configured with the namespace as a prefix, `"crew/no-raw-dates": "error"`, while core rules carry no prefix. By convention the namespace is the package name without `eslint-plugin-`, but you may choose any name as long as the prefix matches it. When the object also has `files`, the plugin is available only to files that object matches. The eslintrc form `plugins: ["react-hooks"]` is rejected, because ESLint 10 removed eslintrc.
go deeper
Recall the three moves: import the plugin, register it under a namespace in the plugins object, and prefix its rules with that namespace in rules.
Explain why plugins is an object of imported plugins: the config chooses the namespace and the exact object, and the eslintrc string array is now a configuration error.
Show you can read the plugin errors: a missing plugin for a given file usually means a files-scoped registration, while a missing rule inside a loaded plugin is a name typo.
Frame namespaces as part of a shared contract: once teams write crew/ rules into many configs, renaming the namespace or the plugin is a coordinated change, not a local edit.
## What a plugin is An ESLint **plugin** is an ordinary JavaScript object, usually the default export of an npm package such as `eslint-plugin-react-hooks` or of a local file. ESLint looks at a few of its properties: - `meta` - the plugin's `name`, `version` and, optionally, a preferred `namespace`. - `rules` - an object mapping rule IDs (without any `/`) to rule definitions. - `configs` - named **presets**, ready-made config objects or arrays that turn the plugin's rules on. - `processors` - named processors that pull JavaScript out of other files. - `languages` - since ESLint 9.7.0 a plugin can also ship a language, so ESLint can lint JSON or Markdown itself. Installing the package does nothing by itself. ESLint's own documentation is explicit that a plugin cannot force its configuration on you: you must load it and say what to turn on. ## Registering it: the `plugins` object In flat config, the only config format in ESLint 10, you import the plugin in `eslint.config.js` and register it under a configuration object's `plugins` key. The value of `plugins` is an **object**: each property name is a **namespace** you choose and each value is the imported plugin object. ```js import crewPlugin from "./eslint/crew-plugin.js"; import { defineConfig } from "eslint/config"; export default defineConfig([ { files: ["**/*.{js,jsx}"], plugins: { crew: crewPlugin }, rules: { "crew/no-raw-dates": "error" }, }, ]); ``` Because the config file does the import, it decides exactly which object is loaded and under which name. The same mechanism works for a published package, a local file, or a **virtual plugin** written inline as `{ rules: { "my-rule": myRule } }`. ## How the namespace names the rules The namespace becomes the prefix of every rule from that plugin in `rules`: 1. Core rules have no prefix: `eqeqeq`, `no-unused-vars`. 2. Plugin rules are `namespace/rule-name`: `crew/no-raw-dates`, `react-hooks/rules-of-hooks`. 3. The prefix is whatever **you** registered, not the package name. Registering `eslint-plugin-jsdoc` as `plugins: { jsd: jsdoc }` means its rules are `jsd/require-description`. By convention the namespace is the package name without the `eslint-plugin-` prefix, so `eslint-plugin-example` becomes `example`. A namespace that does not begin with `@` may not contain a `/`, and a scoped one such as `@eslint/plugin` may. ## Presets register plugins too A plugin's **preset** is itself a config object, and a flat preset normally registers the plugin for you. eslint-plugin-react-hooks' `reactHooks.configs.flat.recommended`, for example, contains `plugins: { "react-hooks": plugin }` and sets rules such as `react-hooks/rules-of-hooks`. That has two consequences: - Your own settings for those rules must use the namespace the preset chose, `react-hooks/...`, even if you would have picked a shorter name. - If you register the same imported plugin yourself under that same namespace, nothing breaks: ESLint compares the objects and they are identical. Plugins can also declare a preferred namespace in `meta.namespace`. When they do and you reference their preset as a string, `defineConfig()` rewrites the preset's rule names to match the namespace you registered. Without that declaration, the preset's prefix is fixed. ## Local and virtual plugins - A local file that exports a plugin object is imported and registered exactly like a package: `plugins: { crew: crewPlugin }`. - A **virtual plugin** is an object literal in the config: `plugins: { local: { rules: { "my-rule": myRule } } }`, configured as `"local/my-rule"`. - Both are useful while a team's rules are still young; publishing them later as a package changes only the import line. ## Why an object and not a list of names In the old eslintrc format, `plugins` was an array of package names, `["react-hooks"]`, and ESLint resolved each name to a package. Flat config replaced that with imported objects: no hidden package resolution, an explicit namespace, and the ability to register a plugin that was never published. ESLint 10 removed eslintrc altogether, so an array in `plugins` is now a configuration error that says it "appears to be in eslintrc format (array of strings) rather than flat config format (object)". ## Errors you will meet | Symptom | Cause | |---|---| | `Could not find plugin "crew" in configuration.` | A rule `crew/...` is configured for a file, but no config object matching that file registers `crew`. | | `Could not find "no-raw-date" in plugin "crew".` | The plugin is loaded but has no rule by that name, usually a typo. | | "appears to be in eslintrc format (array of strings)" | `plugins` was written as an eslintrc-style array. | The first row catches people who scope the registration: when an object has `files`, its plugins are available only to the files it matches, so a rule configured in an object without `files` fails for any file outside that pattern. ## In short Import the plugin, give it a namespace in a `plugins` object, and prefix its rules with that namespace. The rest of plugin use, presets and processors included, builds on this one step.
- Can you use a rule kept in a local file without publishing a plugin?Yes. Import the rule and wrap it in a virtual plugin inside the config: `plugins: { local: { rules: { "my-rule": myRule } } }`, then configure it as `"local/my-rule"`. A whole local plugin file can be imported the same way as a published package, under any namespace you like.
- A config registers `plugins: { crew }` only in an object with `files: ["apps/**/*.jsx"]`, and another object without `files` sets a `crew/` rule. What happens for a `.js` script outside `apps/`?ESLint stops with `Could not find plugin "crew" in configuration.` for that file. Plugins registered in an object with `files` are only available to the files it matches, while the rule setting reaches every file ESLint lints. Register the plugin wherever its rules apply, or scope the rule object the same way.
- Plugins are listed in flat config as an array of package-name strings.
- The rule prefix must be the full npm package name, eslint-plugin- included.
- Installing a plugin package with npm is enough for ESLint to use its rules.
- A plugin registered in one files-scoped object is available to every file.
- Plugin rules can be configured without a prefix, just like core rules.
Assumes ESLint 10: flat config is the only format since 10.0.0, which removed eslintrc and its string-array plugins; language plugins exist since 9.7.0.