In ESLint 10, adding `@crewdeck/eslint-config` beside an app's own eslint-plugin-react-hooks import fails with `Cannot redefine plugin "react-hooks"` - what causes it, and what fixes it?
answer
- plugins merge per file
- same key must mean same object
- two installed copies of one plugin
- register once, configure later
- a second namespace is not an alias
basics
~20 sTwo config objects matching the same file map the namespace react-hooks to different plugin objects, usually two installed copies of the plugin. Register it once, from one copy, and configure its rules in later objects.
solid answer
~50 sFor each file, ESLint merges the `plugins` of every matching config object, and one namespace may point to only one plugin object: registering the identical object twice is fine, but a different object under the same key throws `Cannot redefine plugin "react-hooks"`. The usual cause is two copies on disk: the shared config's dependency resolves to one version of eslint-plugin-react-hooks and the app's own import to another, so the two imports are different objects. Fix it by aligning the versions so only one copy is installed, or by dropping the app's registration and configuring `react-hooks/*` rules in a later object, which can use a plugin an earlier matching object registered. Don't dodge it with a second namespace: the preset's `react-hooks/*` rules and your `hooks/*` rules are then separate rule IDs, so an override on one misses the other.
code
javascript · 14 lines// apps/roster/eslint.config.js - after the fix
import crewdeck from "@crewdeck/eslint-config"; // registers "react-hooks" and "crew"
import { defineConfig } from "eslint/config";
export default defineConfig([
crewdeck, // nested arrays are flattened by defineConfig()
{
files: ["src/**/*.{js,jsx}"],
// no plugins key: "react-hooks" comes from crewdeck's matching objects
rules: {
"react-hooks/exhaustive-deps": "error",
},
},
]);go deeper
Remember that a plugin namespace can point to only one plugin object for a given file, and that a later object can configure rules without registering the plugin again.
Explain how plugins merge across matching objects with an identity check, and why the same import registered twice is fine while two copies are not.
Trace the error to two installed copies, fix it by aligning versions or registering once, and reject a renamed namespace that splits the rule IDs.
Decide who owns plugin registration in a shared config and how version ranges are kept compatible, so many apps stay free of this failure.
## How plugins merge for one file In flat config each **configuration object** can carry a `plugins` object. When ESLint lints a file it merges every object that matches the file, and `plugins` merges key by key: the namespaces from all matching objects end up in one table. One check guards that table. If two objects register the **same namespace** with **different plugin objects**, ESLint throws: `Cannot redefine plugin "react-hooks".` The comparison is by object identity. Registering the same imported object under the same namespace in several objects is normal, and plugin presets do it all the time: `reactHooks.configs.flat.recommended` contains `plugins: { "react-hooks": plugin }`, and listing `plugins: { "react-hooks": reactHooks }` next to it is harmless when both come from the same import. ## Why two objects can differ The error almost always means two **different copies** of one package were loaded: 1. `@crewdeck/eslint-config` lists eslint-plugin-react-hooks in its `dependencies`, as ESLint's docs recommend for plugins a shareable config needs. 2. The app also depends on eslint-plugin-react-hooks, with a version range that does not overlap the shared config's. 3. The package manager installs two copies, one nested under the shared config. 4. The shared config's preset registers its copy as `react-hooks`; the app's object registers the other copy under the same name. 5. Both objects match `src/App.jsx`, so the merge sees two objects for one key and stops the run with a configuration error. A rarer cause is two unrelated plugins that both want the same short namespace. ## Fixing it | Fix | When it fits | |---|---| | Align the app's version range with the shared config's, so one copy is installed | The app needs the plugin for its own reasons | | Remove the app's `plugins` entry and import nothing | The app only adjusts rules the shared config already loads | | Let only one place register the plugin and configure it everywhere else | Always a good shape for shared configs | The second fix relies on a property of the merge worth knowing: a later object **does not need its own `plugins` key** to configure a plugin's rules. As long as some earlier object that matches the same file registers the namespace, `"react-hooks/exhaustive-deps": "error"` in a later object resolves. If no matching object registers it, ESLint reports `Could not find plugin "react-hooks" in configuration.` instead. ## The tempting wrong fix: a second namespace Registering the app's copy as `hooks` makes the error disappear, and introduces a quieter bug: - The preset still configures `react-hooks/rules-of-hooks` and the other `react-hooks/*` rules. - Your config now configures `hooks/...` rules, which are **different rule IDs**. - An override such as `"hooks/exhaustive-deps": "off"` does not touch `react-hooks/exhaustive-deps`, and if both prefixes are turned on, each reports separately. A namespace is not an alias for a package; it is the name ESLint uses for one registration. Two registrations mean two sets of rule IDs. ## Where `meta.namespace` helps, and where it does not A plugin may declare `meta.namespace`. When it does, and you reference one of its presets as a string in `extends`, `defineConfig()` rewrites the preset's rule, processor and language names to the namespace you chose. That rewrite applies only to string references of plugins that declare a namespace. eslint-plugin-react-hooks declares a `name` and `version` in `meta` but no namespace, and its flat preset is used as an object, so its rules stay `react-hooks/*`. ## Preventing it in a shared config - Register each plugin in **one** object of the shared config, and let every other object configure rules against that registration. - Use the namespace the plugin's own presets use, so a consumer's overrides and the presets agree on rule IDs. - Document which plugins the package registers, so app authors know not to import and register them again. - Treat a plugin major version bump in the shared config as a change consumers must coordinate with, because an app pinned to the old major ends up with a second copy. ## Diagnosing - Read the error: it names the namespace, which tells you which plugin is loaded twice. - List the installed copies of that package with your package manager; two versions confirm the cause. - Search the app's config and the shared config for every `plugins` entry with that key. - After the fix, print the merged config for one file to confirm a single registration and the rule settings you expect.
- Why does ESLint compare plugin objects instead of package names?A flat config hands ESLint imported objects, not package names to resolve: the config file imports an object and registers it. Two copies of one package are two objects with possibly different rules and versions, and ESLint cannot know which one a `react-hooks/*` rule should run from, so it refuses rather than picking silently.
- What should `@crewdeck/eslint-config` do so its consumers rarely hit this error?Keep the plugin in `dependencies`, as ESLint's docs advise, register it in exactly one object of its own, document the namespace it uses, and tell apps to configure those rules without re-registering the plugin. Apps that need the plugin directly should keep their version range compatible with the shared config's.
- Registering a plugin in more than one config object always throws Cannot redefine plugin.
- Every object that sets a plugin's rules must register that plugin again.
- Renaming the app's namespace is a safe fix for Cannot redefine plugin.
- Two namespaces for one plugin act as aliases for the same rules.
- ESLint merges two copies of one plugin package by its name.
Assumes ESLint 10 flat config; the plugin-identity check and per-file plugin merge come from flat config, the only format since 10.0.0, and eslint-plugin-react-hooks gained ESLint 10 support in 7.1.0.