Feat: Convert to ESLint Flat Config

.changeset/tidy-mangos-sniff.md

@@ -0,0 +1,5 @@
+---
+"@workleap/eslint-plugin": major
+---
+
+Convert all configs to flat config. Update documentation.

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
         name: Install pnpm
         id: pnpm-install
         with:
-          version: 8
+          version: 9
           run_install: false
 
       - name: Get pnpm store directory

docs/eslint/flat-config-migration.md

@@ -0,0 +1,206 @@
+---
+order: 50
+label: Migrate to Flat Config
+meta:
+    title: Migrate to Flat Config
+---
+
+# Migrate to flat config
+
+Flat config is the new default configuration format for ESLint. It is supported since version 8.23.0, and is the default starting in version 9. Detailed information regarding this format can be fount in 2 blog posts: [Background](https://eslint.org/blog/2022/08/new-config-system-part-1/) and [Introduction to flat config](https://eslint.org/blog/2022/08/new-config-system-part-2/), as well as the [official docs](https://eslint.org/docs/latest/use/configure/).
+
+## High level differences
+
+Previously, ESLint allowed you to use multiple formats to define your config files. Flat config can only use JavaScript. You can import plugins and pre-made configuration objects directly, and manipulate them as necessary.
+
+The `extends` keyword has been removed. Now you simply add multiple _configuration objects_ to an array. Configuration objects will cascade, similar to the `overrides` block of the old config.
+
+The `.eslintignore` file is no longer valid. If you need to exclude files from linting, add them to a configuration block under the `ignores` key.
+
+Config files no longer rely on custom resolution implemented by ESLint. Since they import modules directly, they now rely on Node file resolution. Config files no longer merge down the file tree, either. Every config file acts as if it is the root config file. This means if you have nested configs as well as a true root config (like in a monorepo), you will want to set your top-level config to ignore directories that have their own config files.
+
+## Basic migration steps
+
+1. Create a file called `eslint.config.js`. `@workleap/eslint-config` is published in ESM, so if your project `type` in `package.json` is not `module`, then you should create an `eslint.config.mjs` file instead.
+
+### Initial setup
+
+Import the `@workleap/eslint-config` module. Create a config array and set it as the default export.
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+
+];
+
+export default config;
+```
+
+### Ignoring files
+
+ESLint will no longer use the `.eslintignore` file. If you have one of these files, create a new configuration object with an `ignores` key:
+
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+    {
+        ignores: ["node_modules/", "dist/"]
+    }
+];
+
+export default config;
+```
+
+## Recommended setup - By project type
+
+`@workleap/eslint-config` exposes some pre-built configs based on common project types. Each of these configs are properly set up for **JavaScript**, **TypeScript**, **Jest**, **Testing Library**, **MDX**, **package.json**, and **YAML**. 
+
+By convention, all configs are found at `workleapPlugin.configs`. A flat config can be a single object or an array, but for simplicity, all Workleap configs are exported as arrays. Therefore, each Workleap config must be spread (`...`) into the config array.
+
+| Type | Config Key | Purpose | Additional Configs |
+|---|---|---|---|
+| Web Application | `configs.webApplication` | General purpose web application using React and TypeScript | React<br>JSX A11y<br>Storybook |
+| TypeScript Library | `configs.typeScriptLibrary` | For building a TypeScript library to be consumed by another project |  |
+| React Library | `configs.reactLibrary` | For building a React library to be consumed by another project | React<br>JSX A11y<br>Storybook |
+| Monorepo Workspace | `configs.monorepoWorkspace` | For the top level of a monorepo |  |
+
+For example, to configure ESLint for a React web application, add the project config to your config array:
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+    {
+        ignores: ["node_modules/", "dist/"]
+    },
+    ...workleapPlugin.configs.webApplication
+];
+
+export default config;
+```
+
+You can override individual rules across all configs by adding another configuration object to the array:
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+    {
+        ignores: ["node_modules/", "dist/"]
+    },
+    ...workleapPlugin.configs.webApplication,
+    {
+        rules: {
+            'react/jsx-uses-vars': 'error',
+        }
+    }
+];
+
+export default config;
+```
+
+You can now delete your previous `.eslintrc` config file, as well as your `.eslintignore` file, if you have one. Please refer to the [official migration guide](https://eslint.org/docs/latest/use/configure/migration-guide) for more details.
+
+## Example monorepo setup
+
+Monorepo setups can be more complex, because each package should have its own ESLint rules. With flat config, ESLint will use which ever `eslint.config.js` is the first to be found by traversing up from the directory in which the `eslint` command was run. This means that, by default, individual ESLint configs within monorepo packages will be ignored if ESLint is run from the root directory.
+
+We can mimic the old ESLint behavior by importing each package's ESLint config into the top level and merging them together.
+
+### Monorepo packages
+
+Inside each monorepo package, create a `eslint.config.js` file. Add the config module that matches the package type. For example, a web application would use the `webApplication` config, while a component libary would use the `reactLibrary` config:
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = workleapPlugin.configs.reactLibrary;
+
+export default config;
+```
+
+You can also set custom ignore rules:
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+    ...workleapPlugin.configs.reactLibrary,
+    ignores: ["build/"]
+];
+
+export default config;
+```
+
+### Top level
+
+Create a new `eslint.config.js` at the root of your project. Import the monorepo workspace config.
+
+In order to make it easier to scope config files to monorepo packages, we recommend using [eslint-flat-config-utils](https://github.com/antfu/eslint-flat-config-utils). The `concat` function makes it easier to join multiple configs together. Wrap your configuration objects in the `concat` function because it will automatically merege arrays.
+
+```javascript
+import { concat } from "eslint-flat-config-utils";
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = concat(
+    {
+        ignores: ["node_modules/"]
+    },
+    workleapPlugin.configs.monorepoWorkspace
+);
+
+export default config;
+```
+
+Import each package's `eslint.config.js` and add them to the `concat` function. Wrap each of the package imports with the `extend` function, and provide the relative path to the root of each package. This will scope the files of that config to the given directory, including any ignores.
+
+```javascript
+import { concat } from "eslint-flat-config-utils";
+import workleapPlugin from "@workleap/eslint-config";
+import packageOneConfig from "./packages/one";
+import packageTwoConfig from "./packages/two";
+
+const config = concat(
+    {
+        ignores: ["node_modules/"]
+    },
+    workleapPlugin.configs.monorepoWorkspace,
+    extend(packageOneConfig, "packages/one/"),
+    extend(packageTwoConfig, "packages/two/"),
+);
+
+export default config;
+```
+
+With this setup, you can lint the entire project from the root, or from within each individual package directory.
+
+## Advanced Configuration
+
+We recommend using one of the "by project type" configurations for simplicity and consistency. But if you need to customize further, you can choose to combine [any individual configs](wl-web-configs/eslint/advanced-composition/). Here, we'll compose a config for a project that uses React and TypeScript. 
+
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+    ...workleapPlugin.configs.core,
+    ...workleapPlugin.configs.typescript,
+    ...workleadPlugin.configs.react
+];
+
+export default config;
+```
+
+Some rules may need to be overridden within each nested config object. Since flat configs are entirely JavaScript, we can manipulate the underlying configuration objects directly. For example, to change the file type used by a config object: 
+```javascript
+import workleapPlugin from "@workleap/eslint-config";
+
+const config = [
+    ...workleapPlugin.configs.core,
+    ...workleapPlugin.configs.typescript,
+    ...workleadPlugin.configs.react.map(conf => (
+        {
+            ...conf,
+            files: ["*.js"]
+        }
+    ))
+];
+
+export default config;
+```

eslint.config.js

@@ -0,0 +1,38 @@
+import workleapPlugin from "@workleap/eslint-plugin";
+import { concat, extend } from "eslint-flat-config-utils";
+import packageBrowserslistConfig from "./packages/browserslist-config/eslint.config.mjs";
+import packageEslintPlugin from "./packages/eslint-plugin/eslint.config.js";
+import packagePostcssConfigs from "./packages/postcss-configs/eslint.config.js";
+import packageStylelintConfigs from "./packages/stylelint-configs/eslint.config.mjs";
+import packageSwcConfigs from "./packages/swc-configs/eslint.config.mjs";
+import packageTsupConfigs from "./packages/tsup-configs/eslint.config.mjs";
+import packageWebpackConfigs from "./packages/webpack-configs/eslint.config.js";
+import sampleApp from "./sample/app/eslint.config.js";
+import sampleComponents from "./sample/components/eslint.config.js";
+import sampleUtils from "./sample/utils/eslint.config.js";
+
+const config = concat(
+    {
+        ignores: [
+            "**/dist/",
+            "pnpm-lock.yaml",
+            "*.md",
+            "*.snap",
+            "**/node_modules/",
+            ".github/"
+        ]
+    },
+    workleapPlugin.configs.monorepoWorkspace,
+    extend(packageBrowserslistConfig, "packages/browserslist-config/"),
+    extend(packageEslintPlugin, "packages/eslint-plugin/"),
+    extend(packagePostcssConfigs, "packages/postcss-configs/"),
+    extend(packageStylelintConfigs, "packages/stylelint-configs/"),
+    extend(packageSwcConfigs, "packages/swc-configs/"),
+    extend(packageTsupConfigs, "packages/tsup-configs/"),
+    extend(packageWebpackConfigs, "packages/webpack-configs/"),
+    extend(sampleApp, "sample/app/"),
+    extend(sampleComponents, "sample/components/"),
+    extend(sampleUtils, "sample/utils/")
+);
+
+export default config;

knip.ts

@@ -171,8 +171,6 @@ const config: KnipConfig = {
         "sample/utils": sampleUtilsConfig
     },
     ignoreWorkspaces: [
-        // Until it's migrated to ESLint 9.
-        "packages/eslint-plugin",
         // Until it supports ESM.
         "packages/stylelint-configs"
     ],

package.json

@@ -38,10 +38,10 @@
     "devDependencies": {
         "@changesets/changelog-github": "0.5.0",
         "@changesets/cli": "2.27.1",
-        "@typescript-eslint/parser": "7.6.0",
         "@workleap/eslint-plugin": "workspace:*",
         "@workleap/typescript-configs": "workspace:*",
         "eslint": "8.57.0",
+        "eslint-flat-config-utils": "^0.2.4",
         "installed-check": "9.3.0",
         "jest": "29.7.0",
         "knip": "5.9.4",

packages/browserslist-config/eslint.config.mjs

@@ -0,0 +1,5 @@
+import workleapPlugin from "@workleap/eslint-plugin";
+
+const config = workleapPlugin.configs.typescriptLibrary;
+
+export default config;