docs: how to author plugins with configs that extend other configs (#18753)

alecgibson · web-flow · commit 9fe068c60db4 · 2024-08-07T10:41:19.000-04:00
* docs: how to author plugins with configs that extend other configs It's not immediately clear from the current documentation how authors should migrate configs that extend other configs. According to the [full documentation][1], an array is actually expected, which isn't clear in the migration documentation. This change updates the documentation to include an array example, and links back to the full documentation. [1]: https://eslint.org/docs/latest/extend/plugins#configs-in-plugins * Review markups - fix quote style - remove stale comment - clarify copy on spreading * Copy tweak
diff --git a/docs/src/extend/plugin-migration-flat-config.md b/docs/src/extend/plugin-migration-flat-config.md
@@ -199,8 +199,43 @@ export default [
 ];
 ```
 
+If your config extends other configs, you can export an array:
+
+```js
+const baseConfig = require("./base-config");
+
+module.exports = {
+    configs: {
+        extendedConfig: [
+            baseConfig,
+            {
+                rules: {
+                    "example/rule1": "error",
+                    "example/rule2": "error"
+                }
+            }
+        ],
+    },
+};
+```
+
 You should update your documentation so your plugin users know how to reference the exported configs.
 
+If your exported config is an object, then your users can insert it directly into the config array; if your exported config is an array, then your users should use the spread operator (`...`) to insert the array's items into the config array.
+
+Here's an example with both an object config and an array config:
+
+```js
+import example from "eslint-plugin-example";
+
+export default [
+    example.configs.recommended, // Object, so don't spread
+    ...example.configs.extendedConfig, // Array, so needs spreading
+];
+```
+
+For more information, see the [full documentation](https://eslint.org/docs/latest/extend/plugins#configs-in-plugins).
+
 ## Migrating Environments for Flat Config
 
 Environments are no longer supported in flat config, and so we recommend transitioning your environments into exported configs. For example, suppose you export a `mocha` environment like this:
