docs(linter): add recipe for flat config converter (#18614)

docs/generated/manifests/menus.json

@@ -2252,6 +2252,14 @@
                 "isExternal": false,
                 "children": [],
                 "disableCollapsible": false
+              },
+              {
+                "name": "Switching to ESLint's flat config format",
+                "path": "/recipes/tips-n-tricks/flat-config",
+                "id": "flat-config",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
               }
             ],
             "disableCollapsible": false
@@ -3444,6 +3452,14 @@
             "isExternal": false,
             "children": [],
             "disableCollapsible": false
+          },
+          {
+            "name": "Switching to ESLint's flat config format",
+            "path": "/recipes/tips-n-tricks/flat-config",
+            "id": "flat-config",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
           }
         ],
         "disableCollapsible": false
@@ -3592,6 +3608,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Switching to ESLint's flat config format",
+        "path": "/recipes/tips-n-tricks/flat-config",
+        "id": "flat-config",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Troubleshooting",
         "path": "/recipes/troubleshooting",

docs/generated/manifests/nx.json

@@ -2808,6 +2808,16 @@
             "isExternal": false,
             "path": "/recipes/tips-n-tricks/yarn-pnp",
             "tags": ["yarn", "Plug and Play"]
+          },
+          {
+            "id": "flat-config",
+            "name": "Switching to ESLint's flat config format",
+            "description": "",
+            "file": "shared/recipes/tips-n-tricks/migrating-to-flat-eslint",
+            "itemList": [],
+            "isExternal": false,
+            "path": "/recipes/tips-n-tricks/flat-config",
+            "tags": ["eslint", "flat config"]
           }
         ],
         "isExternal": false,
@@ -4296,6 +4306,16 @@
         "isExternal": false,
         "path": "/recipes/tips-n-tricks/yarn-pnp",
         "tags": ["yarn", "Plug and Play"]
+      },
+      {
+        "id": "flat-config",
+        "name": "Switching to ESLint's flat config format",
+        "description": "",
+        "file": "shared/recipes/tips-n-tricks/migrating-to-flat-eslint",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/recipes/tips-n-tricks/flat-config",
+        "tags": ["eslint", "flat config"]
       }
     ],
     "isExternal": false,
@@ -4482,6 +4502,16 @@
     "path": "/recipes/tips-n-tricks/yarn-pnp",
     "tags": ["yarn", "Plug and Play"]
   },
+  "/recipes/tips-n-tricks/flat-config": {
+    "id": "flat-config",
+    "name": "Switching to ESLint's flat config format",
+    "description": "",
+    "file": "shared/recipes/tips-n-tricks/migrating-to-flat-eslint",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/recipes/tips-n-tricks/flat-config",
+    "tags": ["eslint", "flat config"]
+  },
   "/recipes/troubleshooting": {
     "id": "troubleshooting",
     "name": "Troubleshooting",

docs/generated/manifests/packages.json

@@ -1142,7 +1142,7 @@
         "type": "generator"
       },
       "/packages/linter/generators/convert-to-flat-config": {
-        "description": "Convert an Nx workspace to a Flat ESLint config.",
+        "description": "Convert an Nx workspace's ESLint configs to use Flat Config.",
         "file": "generated/packages/linter/generators/convert-to-flat-config.json",
         "hidden": false,
         "name": "convert-to-flat-config",

docs/generated/manifests/tags.json

@@ -1008,6 +1008,24 @@
       "path": "/recipes/tips-n-tricks/yarn-pnp"
     }
   ],
+  "eslint": [
+    {
+      "description": "",
+      "file": "shared/recipes/tips-n-tricks/migrating-to-flat-eslint",
+      "id": "flat-config",
+      "name": "Switching to ESLint's flat config format",
+      "path": "/recipes/tips-n-tricks/flat-config"
+    }
+  ],
+  "flat config": [
+    {
+      "description": "",
+      "file": "shared/recipes/tips-n-tricks/migrating-to-flat-eslint",
+      "id": "flat-config",
+      "name": "Switching to ESLint's flat config format",
+      "path": "/recipes/tips-n-tricks/flat-config"
+    }
+  ],
   "deno": [
     {
       "description": "",

docs/generated/packages-metadata.json

@@ -1125,7 +1125,7 @@
         "type": "generator"
       },
       {
-        "description": "Convert an Nx workspace to a Flat ESLint config.",
+        "description": "Convert an Nx workspace's ESLint configs to use Flat Config.",
         "file": "generated/packages/linter/generators/convert-to-flat-config.json",
         "hidden": false,
         "name": "convert-to-flat-config",

docs/generated/packages/linter/documents/overview.md

@@ -28,6 +28,7 @@ nx lint my-lib
 
 ## Utils
 
+- [convert-to-flat-config](/packages/linter/generators/convert-to-flat-config) - Converts the workspace's [ESLint](https://eslint.org/) configs to the new [Flat Config](https://eslint.org/blog/2022/08/new-config-system-part-2)
 - **Deprecated** [convert-tslint-to-eslint](/packages/angular/generators/convert-tslint-to-eslint) - Converts a project linter from [TSLint](https://palantir.github.io/tslint/) to [ESLint](https://eslint.org/)
 
 ## ESLint plugin

docs/generated/packages/linter/generators/convert-to-flat-config.json

@@ -5,7 +5,7 @@
     "$schema": "http://json-schema.org/schema",
     "$id": "ConvertToFlatConfig",
     "cli": "nx",
-    "description": "Convert an Nx workspace to a Flat ESLint config.",
+    "description": "Convert an Nx workspace's ESLint configs to use Flat Config.",
     "type": "object",
     "properties": {
       "skipFormat": {
@@ -19,7 +19,7 @@
     "required": [],
     "presets": []
   },
-  "description": "Convert an Nx workspace to a Flat ESLint config.",
+  "description": "Convert an Nx workspace's ESLint configs to use Flat Config.",
   "implementation": "/packages/linter/src/generators/convert-to-flat-config/generator.ts",
   "aliases": [],
   "hidden": false,

docs/map.json

@@ -985,6 +985,12 @@
                   "id": "yarn-pnp",
                   "tags": ["yarn", "Plug and Play"],
                   "file": "shared/recipes/yarn-pnp"
+                },
+                {
+                  "name": "Switching to ESLint's flat config format",
+                  "id": "flat-config",
+                  "tags": ["eslint", "flat config"],
+                  "file": "shared/recipes/tips-n-tricks/migrating-to-flat-eslint"
                 }
               ]
             },

docs/shared/packages/linter/linter-plugin.md

@@ -28,6 +28,7 @@ nx lint my-lib
 
 ## Utils
 
+- [convert-to-flat-config](/packages/linter/generators/convert-to-flat-config) - Converts the workspace's [ESLint](https://eslint.org/) configs to the new [Flat Config](https://eslint.org/blog/2022/08/new-config-system-part-2)
 - **Deprecated** [convert-tslint-to-eslint](/packages/angular/generators/convert-tslint-to-eslint) - Converts a project linter from [TSLint](https://palantir.github.io/tslint/) to [ESLint](https://eslint.org/)
 
 ## ESLint plugin

docs/shared/recipes/tips-n-tricks/migrating-to-flat-eslint.md

@@ -0,0 +1,173 @@
+# Switching to ESLint's flat config format
+
+Version 8 of ESLint introduced a new configuration format called [Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files-new). The next major version will use this config format by default. The purpose of this format is to:
+
+- push towards a single configuration format (in contrast to the existing `JSON`, `Yaml` and `JS`-based configs)
+- enforce explicit native loading (instead of the implicit imports in `JSON` and `Yaml`)
+- use a flat cascading of rules (instead of a mix of rules and overrides)
+
+See below a direct comparison between `JSON`, `JS` and `Flat` config:
+{% tabs %}
+{% tab label="Flat" %}
+
+```js {% fileName="eslint.config.js" %}
+// the older versions were magically interpreting all the imports
+// in flat config we do it explicitly
+const nxPlugin = require('@nx/eslint-plugin');
+const js = require('@eslint/js');
+const baseConfig = require('./eslint.base.config.js');
+const globals = require('globals');
+const jsoncParser = require('jsonc-eslint-parser');
+const tsParser = require('@typescript-eslint/parser');
+
+module.exports = [
+  js.configs.recommended,
+  // this will spread the export blocks from the base config
+  ...baseConfig,
+  { plugins: { '@nx': nxPlugin } },
+  {
+    languageOptions: {
+      parser: tsParser,
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      '@typescript-eslint/explicit-module-boundary-types': ['error'],
+    },
+  },
+  // there are no overrides, all the config blocks are "flat"
+  {
+    files: ['*.json'],
+    languageOptions: {
+      parser: jsoncParser,
+    },
+    rules: {},
+  },
+  {
+    files: ['*.ts', '*.tsx', '*.js', '*.jsx'],
+    rules: {
+      '@nx/enforce-module-boundaries': [
+        'error',
+        {
+          enforceBuildableLibDependency: true,
+          allow: [],
+          depConstraints: [
+            {
+              sourceTag: '*',
+              onlyDependOnLibsWithTags: ['*'],
+            },
+          ],
+        },
+      ],
+    },
+  },
+];
+```
+
+{% /tab %}
+{% tab label="JSON" %}
+
+```json {% fileName=".eslintrc.json" %}
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "env": {
+    "node": true
+  },
+  "extends": ["eslint:recommended", "./.eslintrc.base.json"],
+  "plugins": ["@nx"],
+  "rules": {
+    "@typescript-eslint/explicit-module-boundary-types": "error"
+  },
+  "overrides": [
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {
+        "@nx/enforce-module-boundaries": [
+          "error",
+          {
+            "enforceBuildableLibDependency": true,
+            "allow": [],
+            "depConstraints": [
+              {
+                "sourceTag": "*",
+                "onlyDependOnLibsWithTags": ["*"]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+{% /tab %}
+{% tab label="JS" %}
+
+```js {% fileName=".eslintrc.js" %}
+module.exports = {
+  root: true,
+  env: {
+    node: true,
+  },
+  parser: '@typescript-eslint/parser',
+  extends: ['eslint:recommended', './.eslintrc.base.js'],
+  plugins: ['@nx'],
+  rules: {
+    '@typescript-eslint/explicit-module-boundary-types': ['error'],
+  },
+  overrides: [
+    {
+      files: ['*.json'],
+      parser: 'jsonc-eslint-parser',
+      rules: {},
+    },
+    {
+      files: ['*.ts', '*.tsx', '*.js', '*.jsx'],
+      rules: {
+        '@nx/enforce-module-boundaries': [
+          'error',
+          {
+            enforceBuildableLibDependency: true,
+            allow: [],
+            depConstraints: [
+              {
+                sourceTag: '*',
+                onlyDependOnLibsWithTags: ['*'],
+              },
+            ],
+          },
+        ],
+      },
+    },
+  ],
+};
+```
+
+{% /tab %}
+{% /tabs %}
+
+For additional details, head over to [ESLint's official blog post](https://eslint.org/blog/2022/08/new-config-system-part-2/).
+
+Since version 16.7.0, Nx supports the usage of flat config in the [@nx/linter:eslint](/packages/linter/executors/eslint) executor and `@nx/*` generators, and provides an automated config conversion from `.eslintrc.json` config files.
+
+## Converting workspace from .eslintrc.json to flat config
+
+To convert workspace ESLint configurations from the default `.eslintrc.json` to the new flat config you need to run:
+
+```shell
+ nx g @nx/linter:convert-to-flat-config
+```
+
+The generator will go through all the projects and convert their configurations to the new format. It will also convert the base `.eslintrc.json` and `.eslintignore`.
+
+## Correctness and best practices
+
+The purpose of this generator is to create a flat config that works the same way as the original `JSON` config did. Depending on the complexity of your original config, it may be using the `FlatCompat` utility to provide a compatibility wrapper around parts of the original config. You can improve those by following the [official migration guide](https://eslint.org/docs/latest/use/configure/migration-guide).

docs/shared/reference/sitemap.md

@@ -168,6 +168,7 @@
       - [Altering Migration Process](/recipes/tips-n-tricks/advanced-update)
       - [Running Custom Commands](/recipes/tips-n-tricks/run-commands-executor)
       - [Using Yarn PnP](/recipes/tips-n-tricks/yarn-pnp)
+      - [Switching to ESLint's flat config format](/recipes/tips-n-tricks/flat-config)
     - [Troubleshooting](/recipes/troubleshooting)
       - [Resolve Circular Dependencies](/recipes/troubleshooting/resolve-circular-dependencies)
       - [Troubleshooting Nx Install Issues](/recipes/troubleshooting/troubleshoot-nx-install-issues)

packages/linter/generators.json

@@ -29,7 +29,7 @@
     "convert-to-flat-config": {
       "factory": "./src/generators/convert-to-flat-config/generator",
       "schema": "./src/generators/convert-to-flat-config/schema.json",
-      "description": "Convert an Nx workspace to a Flat ESLint config."
+      "description": "Convert an Nx workspace's ESLint configs to use Flat Config."
     }
   }
 }

packages/linter/src/generators/convert-to-flat-config/schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/schema",
   "$id": "ConvertToFlatConfig",
   "cli": "nx",
-  "description": "Convert an Nx workspace to a Flat ESLint config.",
+  "description": "Convert an Nx workspace's ESLint configs to use Flat Config.",
   "type": "object",
   "properties": {
     "skipFormat": {