From 038c26cade3c85c823ba2eafd52bb91ae458f2b2 Mon Sep 17 00:00:00 2001
From: jwbth <33615628+jwbth@users.noreply.github.com>
Date: Thu, 28 Mar 2024 22:38:13 +0400
Subject: [PATCH] [readme] Clarify how to install the plugin

The markup was misleading, as it put several alternatives into one block of code while not making it clear where the alternatives begin and end, forcing the reader to think hard about it.

Also converted most yaml examples to jsonc.

Co-authored-by: jwbth <33615628+jwbth@users.noreply.github.com>
Co-authored-by: Jordan Harband <ljharb@gmail.com>
---
 CHANGELOG.md |   3 +
 README.md    | 176 ++++++++++++++++++++++++++++++++-------------------
 2 files changed, 115 insertions(+), 64 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92431a156..9022dc887 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 - [Refactor] `exportMapBuilder`: avoid hoisting ([#2989], thanks [@soryy708])
 - [Refactor] `ExportMap`: extract "builder" logic to separate files ([#2991], thanks [@soryy708])
 - [Docs] [`order`]: update the description of the `pathGroupsExcludedImportTypes` option ([#3036], thanks [@liby])
+- [readme] Clarify how to install the plugin ([#2993], thanks [@jwbth])
 
 ## [2.29.1] - 2023-12-14
 
@@ -1133,6 +1134,7 @@ for info on changes for earlier releases.
 [#3011]: https://github.com/import-js/eslint-plugin-import/pull/3011
 [#3004]: https://github.com/import-js/eslint-plugin-import/pull/3004
 [#2998]: https://github.com/import-js/eslint-plugin-import/pull/2998
+[#2993]: https://github.com/import-js/eslint-plugin-import/pull/2993
 [#2991]: https://github.com/import-js/eslint-plugin-import/pull/2991
 [#2989]: https://github.com/import-js/eslint-plugin-import/pull/2989
 [#2987]: https://github.com/import-js/eslint-plugin-import/pull/2987
@@ -1835,6 +1837,7 @@ for info on changes for earlier releases.
 [@jseminck]: https://github.com/jseminck
 [@julien1619]: https://github.com/julien1619
 [@justinanastos]: https://github.com/justinanastos
+[@jwbth]: https://github.com/jwbth
 [@k15a]: https://github.com/k15a
 [@kentcdodds]: https://github.com/kentcdodds
 [@kevin940726]: https://github.com/kevin940726
diff --git a/README.md b/README.md
index bf563f4d7..8cc723423 100644
--- a/README.md
+++ b/README.md
@@ -108,35 +108,37 @@ npm install eslint-plugin-import --save-dev
 
 ### Config - Legacy (`.eslintrc`)
 
-All rules are off by default. However, you may configure them manually
-in your `.eslintrc.(yml|json|js)`, or extend one of the canned configs:
+All rules are off by default. However, you may extend one of the preset configs, or configure them manually in your `.eslintrc.(yml|json|js)`.
 
-```yaml
----
-extends:
-  - eslint:recommended
-  - plugin:import/recommended
-  # alternatively, 'recommended' is the combination of these two rule sets:
-  - plugin:import/errors
-  - plugin:import/warnings
-
-# or configure manually:
-plugins:
-  - import
-
-rules:
-  import/no-unresolved: [2, { commonjs: true, amd: true }]
-  import/named: 2
-  import/namespace: 2
-  import/default: 2
-  import/export: 2
-  # etc...
+ - Extending a preset config:
+
+```jsonc
+{
+  "extends": [
+     "eslint:recommended",
+     "plugin:import/recommended",
+  ],
+}
+```
+
+ - Configuring manually:
+
+```jsonc
+{
+  "rules": {
+    "import/no-unresolved": ["error", { "commonjs": true, "amd": true }]
+    "import/named": "error",
+    "import/namespace": "error",
+    "import/default": "error",
+    "import/export": "error",
+    // etc...
+  },
+},
 ```
 
 ### Config - Flat (`eslint.config.js`)
 
-All rules are off by default. However, you may configure them manually
-in your `eslint.config.(js|cjs|mjs)`, or extend one of the canned configs:
+All rules are off by default. However, you may configure them manually in your `eslint.config.(js|cjs|mjs)`, or extend one of the preset configs:
 
 ```js
 import importPlugin from 'eslint-plugin-import';
@@ -166,18 +168,23 @@ You may use the following snippet or assemble your own config using the granular
 
 Make sure you have installed [`@typescript-eslint/parser`] and [`eslint-import-resolver-typescript`] which are used in the following configuration.
 
-```yaml
-extends:
-  - eslint:recommended
-  - plugin:import/recommended
-# the following lines do the trick
-  - plugin:import/typescript
-settings:
-  import/resolver:
-    # You will also need to install and configure the TypeScript resolver
-    # See also https://github.com/import-js/eslint-import-resolver-typescript#configuration
-    typescript: true
-    node: true
+```jsonc
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:import/recommended",
+// the following lines do the trick
+    "plugin:import/typescript",
+  ],
+  "settings": {
+    "import/resolver": {
+      // You will also need to install and configure the TypeScript resolver
+      // See also https://github.com/import-js/eslint-import-resolver-typescript#configuration
+      "typescript": true,
+      "node": true,
+    },
+  },
+}
 ```
 
 [`@typescript-eslint/parser`]: https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser
@@ -206,6 +213,16 @@ You can reference resolvers in several ways (in order of precedence):
 
  - as a conventional `eslint-import-resolver` name, like `eslint-import-resolver-foo`:
 
+ ```jsonc
+// .eslintrc
+{
+  "settings": {
+    // uses 'eslint-import-resolver-foo':
+    "import/resolver": "foo",
+  },
+}
+```
+
 ```yaml
 # .eslintrc.yml
 settings:
@@ -226,6 +243,15 @@ module.exports = {
 
  - with a full npm module name, like `my-awesome-npm-module`:
 
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/resolver": "my-awesome-npm-module",
+  },
+}
+```
+
 ```yaml
 # .eslintrc.yml
 settings:
@@ -321,11 +347,15 @@ In practice, this means rules other than [`no-unresolved`](./docs/rules/no-unres
 
 `no-unresolved` has its own [`ignore`](./docs/rules/no-unresolved.md#ignore) setting.
 
-```yaml
-settings:
-  import/ignore:
-    - \.coffee$          # fraught with parse errors
-    - \.(scss|less|css)$ # can't parse unprocessed CSS modules, either
+```jsonc
+{
+  "settings": {
+    "import/ignore": [
+      "\.coffee$", // fraught with parse errors
+      "\.(scss|less|css)$", // can't parse unprocessed CSS modules, either
+    ],
+  },
+}
 ```
 
 ### `import/core-modules`
@@ -344,10 +374,13 @@ import 'electron'  // without extra config, will be flagged as unresolved!
 that would otherwise be unresolved. To avoid this, you may provide `electron` as a
 core module:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/core-modules: [ electron ]
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/core-modules": ["electron"],
+  },
+}
 ```
 
 In Electron's specific case, there is a shared config named `electron`
@@ -380,11 +413,15 @@ dependency parser will require and use the map key as the parser instead of the
 configured ESLint parser. This is useful if you're inter-op-ing with TypeScript
 directly using webpack, for example:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/parsers:
-    "@typescript-eslint/parser": [ .ts, .tsx ]
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/parsers": {
+      "@typescript-eslint/parser": [".ts", ".tsx"],
+    },
+  },
+}
 ```
 
 In this case, [`@typescript-eslint/parser`](https://www.npmjs.com/package/@typescript-eslint/parser)
@@ -414,20 +451,28 @@ For long-lasting processes, like [`eslint_d`] or [`eslint-loader`], however, it'
 
 If you never use [`eslint_d`] or [`eslint-loader`], you may set the cache lifetime to `Infinity` and everything should be fine:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/cache:
-    lifetime: ∞  # or Infinity
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/cache": {
+      "lifetime": "∞", // or Infinity, in a JS config
+    },
+  },
+}
 ```
 
 Otherwise, set some integer, and cache entries will be evicted after that many seconds have elapsed:
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/cache:
-    lifetime: 5  # 30 is the default
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/cache": {
+      "lifetime": 5, // 30 is the default
+    },
+  },
+}
 ```
 
 [`eslint_d`]: https://www.npmjs.com/package/eslint_d
@@ -441,10 +486,13 @@ By default, any package referenced from [`import/external-module-folders`](#impo
 
 For example, if your packages in a monorepo are all in `@scope`, you can configure `import/internal-regex` like this
 
-```yaml
-# .eslintrc.yml
-settings:
-  import/internal-regex: ^@scope/
+```jsonc
+// .eslintrc
+{
+  "settings": {
+    "import/internal-regex": "^@scope/",
+  },
+}
 ```
 
 ## SublimeLinter-eslint