diff --git a/docs/src/use/troubleshooting/couldnt-determine-the-plugin-uniquely.md b/docs/src/use/troubleshooting/couldnt-determine-the-plugin-uniquely.md new file mode 100644 index 00000000000..5065cc2416b --- /dev/null +++ b/docs/src/use/troubleshooting/couldnt-determine-the-plugin-uniquely.md @@ -0,0 +1,54 @@ +--- +title: ESLint couldn't determine the plugin … uniquely +eleventyNavigation: + key: couldn't determine plugin uniquely + parent: troubleshooting + title: ESLint couldn't determine the plugin … uniquely +--- + +## Symptoms + +When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies: + +```plaintext +ESLint couldn't determine the plugin "${pluginId}" uniquely. + +- ${filePath} (loaded in "${importerName}") +- ${filePath} (loaded in "${importerName}") +... + +Please remove the "plugins" setting from either config or remove either plugin installation. +``` + +## Cause + +ESLint configuration files allow loading in plugins that may include other plugins. +A plugin package might be specified as a dependency of both your package and one or more ESLint plugins. +Legacy ESLint configuration files may use `extends` to include other configurations. +Those configurations may depend on plugins to provide certain functionality in the configuration. + +For example, if your config depends on `eslint-plugin-a@2` and `eslint-plugin-b@3`, and you extend `eslint-config-b` that depends on `eslint-plugin-a@1`, then the `eslint-plugin-a` package might have two different versions on disk: + +* `node_modules/eslint-plugin-a` +* `node_modules/eslint-plugin-b/node_modules/eslint-plugin-a` + +If the legacy ESLint configuration system sees that both plugins exists in multiple places with different versions, it won't know which one to use. + +Note that this issue is only present in the legacy eslintrc configurations. +The new ["flat" config system](../configure/configuration-files) has you `import` the dependencies yourself, removing the need for ESLint to attempt to determine their version uniquely. + +## Resolution + +Common resolutions for this issue include: + +* Upgrading all versions of all packages to their latest version +* Running `npm dedupe` or the equivalent package manager command to deduplicate packages, if their version ranges are compatible +* Using `overrides` or the equivalent package manager `package.json` field, to force a specific version of a plugin package + * Note that this may cause bugs in linting if the plugin package had breaking changes between versions + +## Resources + +For more information, see: + +* [Configure Plugins](../configure/plugins) for documentation on how to extend from plugins +* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins diff --git a/docs/src/use/troubleshooting/couldnt-find-the-config.md b/docs/src/use/troubleshooting/couldnt-find-the-config.md new file mode 100644 index 00000000000..6208e5087ca --- /dev/null +++ b/docs/src/use/troubleshooting/couldnt-find-the-config.md @@ -0,0 +1,62 @@ +--- +title: ESLint couldn't find the config … to extend from +eleventyNavigation: + key: couldn't find the config to extend from + parent: troubleshooting + title: ESLint couldn't find the config … to extend from +--- + +## Symptoms + +When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies: + +```plaintext +ESLint couldn't find the config "${configName}" to extend from. Please check that the name of the config is correct. + +The config "${configName}" was referenced from the config file in "${importerName}". +``` + +## Cause + +ESLint configuration files specify shareable configs by their package name in the `extends` array. +That package name is passed to the Node.js `require()`, which looks up the package under local `node_modules/` directories. +For example, the following ESLint config will first try to load a module located at `node_modules/eslint-config-yours`: + +```js +module.exports = { + extends: ["eslint-config-yours"], +}; +``` + +The error is output when you attempt to extend from a configuration and the package for that configuration is not found in any searched `node_modules/`. + +Common reasons for this occurring include: + +* Not running `npm install` or the equivalent package manager command +* Mistyping the case-sensitive name of the package and/or configuration + +### Config Name Variations + +Note that ESLint supports several config name formats: + +* The `eslint-config-` config name prefix may be omitted for brevity, e.g. `extends: ["yours"]` + * [`@` npm scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope) put the `eslint-config-` prefix after the org scope, e.g. `extends: ["@org/yours"]` to load from `@org/eslint-config-yours` +* A `plugin:` prefix indicates a config is loaded from a shared plugin, e.g. `extends: [plugin:yours/recommended]` to load from `eslint-plugin-yours` + +## Resolution + +Common resolutions for this issue include: + +* Upgrading all versions of all packages to their latest version +* Adding the config as a `devDependency` in your `package.json` +* Running `npm install` or the equivalent package manager command +* Checking that the name in your config file matches the name of the config package + +## Resources + +For more information, see: + +* [Legacy ESLint configuration files](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on the legacy ESLint configuration format + * [Legacy ESLint configuration files > Using a shareable configuration package](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on using shareable configurations +* [Share Configurations](../../extend/shareable-configs) for documentation on how to define standalone shared configs +* [Create Plugins > Configs in Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define shared configs in plugins diff --git a/docs/src/use/troubleshooting/couldnt-find-the-plugin.md b/docs/src/use/troubleshooting/couldnt-find-the-plugin.md new file mode 100644 index 00000000000..bc2241e8fa6 --- /dev/null +++ b/docs/src/use/troubleshooting/couldnt-find-the-plugin.md @@ -0,0 +1,65 @@ +--- +title: ESLint couldn't find the plugin … +eleventyNavigation: + key: couldn't find the plugin + parent: troubleshooting + title: ESLint couldn't find the plugin … +--- + +## Symptoms + +When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies: + +```plaintext +ESLint couldn't find the plugin "${pluginName}". + +(The package "${pluginName}" was not found when loaded as a Node module from the directory "${resolvePluginsRelativeTo}".) + +It's likely that the plugin isn't installed correctly. Try reinstalling by running the following: + + npm install ${pluginName}@latest --save-dev + +The plugin "${pluginName}" was referenced from the config file in "${importerName}". +``` + +## Cause + +[Legacy ESLint configuration files](../configure/configuration-files-deprecated) specify shareable configs by their package name. +That package name is passed to the Node.js `require()`, which looks up the package under local `node_modules/` directories. +For example, the following ESLint config will first try to load a module located at `node_modules/eslint-plugin-yours`: + +```js +module.exports = { + extends: ["plugin:eslint-plugin-yours/config-name"], +}; +``` + +If the package is not found in any searched `node_modules/`, ESLint will print the aforementioned error. + +Common reasons for this occurring include: + +* Not running `npm install` or the equivalent package manager command +* Mistyping the case-sensitive name of the plugin + +### Plugin Name Variations + +Note that the `eslint-plugin-` plugin name prefix may be omitted for brevity, e.g. `extends: ["yours"]`. + +[`@` npm scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope) put the `eslint-plugin-` prefix after the org scope, e.g. `extends: ["@org/yours"]` to load from `@org/eslint-plugin-yours`. + +## Resolution + +Common resolutions for this issue include: + +* Upgrading all versions of all packages to their latest version +* Adding the plugin as a `devDependency` in your `package.json` +* Running `npm install` or the equivalent package manager command +* Checking that the name in your config file matches the name of the plugin package + +## Resources + +For more information, see: + +* [Legacy ESLint configuration files](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on the legacy ESLint configuration format +* [Configure Plugins](../configure/plugins) for documentation on how to extend from plugins +* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins diff --git a/docs/src/use/troubleshooting/index.md b/docs/src/use/troubleshooting/index.md new file mode 100644 index 00000000000..25cbbc87f3a --- /dev/null +++ b/docs/src/use/troubleshooting/index.md @@ -0,0 +1,18 @@ +--- +title: Troubleshooting +eleventyNavigation: + key: troubleshooting + title: Troubleshooting + parent: use eslint + order: 8 +--- + +This page serves as a reference for common issues working with ESLint. + +* [`ESLint couldn't determine the plugin … uniquely`](./couldnt-determine-the-plugin-uniquely) +* [`ESLint couldn't find the config … to extend from`](./couldnt-find-the-config) +* [`ESLint couldn't find the plugin …`](./couldnt-find-the-plugin) + +Issues oftentimes can be resolved by updating the to latest versions of the `eslint` package and any related packages, such as for ESLint shareable configs and plugins. + +If you still can't figure out the problem, please stop by to chat with the team. diff --git a/messages/plugin-conflict.js b/messages/plugin-conflict.js index c8c060e2f05..4113a538fc9 100644 --- a/messages/plugin-conflict.js +++ b/messages/plugin-conflict.js @@ -15,7 +15,7 @@ module.exports = function(it) { Please remove the "plugins" setting from either config or remove either plugin installation. -If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team. +If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting. `; return result; diff --git a/messages/plugin-invalid.js b/messages/plugin-invalid.js index 8b471d4a336..4c60e41d319 100644 --- a/messages/plugin-invalid.js +++ b/messages/plugin-invalid.js @@ -11,6 +11,6 @@ module.exports = function(it) { "${configName}" was referenced from the config file in "${importerName}". -If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team. +If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting. `.trimStart(); }; diff --git a/messages/plugin-missing.js b/messages/plugin-missing.js index 0b7d34e3aa5..366ec4500e5 100644 --- a/messages/plugin-missing.js +++ b/messages/plugin-missing.js @@ -14,6 +14,6 @@ It's likely that the plugin isn't installed correctly. Try reinstalling by runni The plugin "${pluginName}" was referenced from the config file in "${importerName}". -If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team. +If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting. `.trimStart(); };