@kirklin/eslint-config 2.1.0 → 2.3.0

package/README.md

@@ -36,7 +36,7 @@
 - [ESLint Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new), compose easily!
 - Using [ESLint Stylistic](https://github.com/eslint-stylistic/eslint-stylistic)
 - Respects `.gitignore` by default
-- Optional [React](#react), [Svelte](#svelte), [UnoCSS](#unocss) support
+- Optional [React](#react), [Svelte](#svelte), [UnoCSS](#unocss), [Astro](#astro), [Solid](#solid) support
 - Optional [formatters](#formatters) support for CSS, HTML, etc.
 - **Style principle**: Minimal for reading, stable for diff, consistent
 
@@ -45,45 +45,46 @@
 
 ## Usage
 
-### Install
+### Starter Wizard
+
+We provided a CLI tool to help you set up your project, or migrate from the legacy config to the new flat config with one command.
 
 ```bash
-pnpm i -D eslint @kirklin/eslint-config
+npx @kirklin/eslint-config@latest
 ```
 
-### Create config file
-
-With [`"type": "module"`](https://nodejs.org/api/packages.html#type) in `package.json` (recommended):
+### Manual Install
 
-```js
-// eslint.config.js
-import kirklin from "@kirklin/eslint-config";
+If you prefer to set up manually:
 
-export default kirklin();
+```bash
+pnpm i -D eslint @kirklin/eslint-config
 ```
 
-With CJS:
+And create `eslint.config.mjs` in your project root:
 
 ```js
-// eslint.config.js
-const kirklin = require("@kirklin/eslint-config").default;
+// eslint.config.mjs
+import kirklin from "@kirklin/eslint-config";
 
-module.exports = kirklin();
+export default kirklin();
 ```
 
-> [!TIP]
-> ESLint only detects `eslint.config.js` as the flat config entry, meaning you need to put `type: module` in your `package.json` or you have to use CJS in `eslint.config.js`. If you want explicit extension like `.mjs` or `.cjs`, or even `eslint.config.ts`, you can install [`eslint-ts-patch`](https://github.com/antfu/eslint-ts-patch) to fix it.
-
+<details>
+<summary>
 Combined with legacy config:
+</summary>
+
+If you still use some configs from the legacy eslintrc format, you can use the [`@eslint/eslintrc`](https://www.npmjs.com/package/@eslint/eslintrc) package to convert them to the flat config.
 
 ```js
-// eslint.config.js
-const kirklin = require("@kirklin/eslint-config").default;
-const { FlatCompat } = require("@eslint/eslintrc");
+// eslint.config.mjs
+import kirklin from "@kirklin/eslint-config";
+import { FlatCompat } from "@eslint/eslintrc";
 
 const compat = new FlatCompat();
 
-module.exports = kirklin(
+export default kirklin(
   {
     ignores: [],
   },
@@ -102,6 +103,8 @@ module.exports = kirklin(
 
 > Note that `.eslintignore` no longer works in Flat config, see [customization](#customization) for more details.
 
+</details>
+
 ### Add script for package.json
 
 For example:
@@ -115,17 +118,7 @@ For example:
 }
 ```
 
-### Migration
-
-We provided an experimental CLI tool to help you migrate from the legacy config to the new flat config.
-
-```bash
-npx @kirklin/eslint-config@latest
-```
-
-Before running the migration, make sure to commit your unsaved changes first.
-
-## VS Code support (auto fix)
+## VS Code support (auto fix on save)
 
 Install [VS Code ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
 
@@ -172,7 +165,9 @@ Add the following settings to your `.vscode/settings.json`:
     "json",
     "jsonc",
     "yaml",
-    "toml"
+    "toml",
+    "gql",
+    "graphql"
   ]
 }
 ```
@@ -304,7 +299,7 @@ Since flat config requires us to explicitly provide the plugin names (instead of
 
 | New Prefix | Original Prefix        | Source Plugin                                                                              |
 | ---------- | ---------------------- | ------------------------------------------------------------------------------------------ |
-| `import/*` | `i/*`                  | [eslint-plugin-i](https://github.com/un-es/eslint-plugin-i)                                |
+| `import/*` | `import-x/*`           | [eslint-plugin-import-x](https://github.com/un-es/eslint-plugin-import-x)                  |
 | `node/*`   | `n/*`                  | [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)                     |
 | `yaml/*`   | `yml/*`                | [eslint-plugin-yml](https://github.com/ota-meshi/eslint-plugin-yml)                        |
 | `ts/*`     | `@typescript-eslint/*` | [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint) |
@@ -320,6 +315,17 @@ When you want to override rules, or disable them inline, you need to update to t
 type foo = { bar: 2 }
 ```
 
+> [!NOTE]
+> About plugin renaming - it is actually rather a dangrous move that might leading to potential naming collisions, pointed out [here](https://github.com/eslint/eslint/discussions/17766) and [here](https://github.com/prettier/eslint-config-prettier#eslintconfigjs-flat-config-plugin-caveat). As this config also very **personal** and **opinionated**, I ambitiously position this config as the only **"top-level"** config per project, that might pivots the taste of how rules are named.
+>
+> This config cares more about the user-facings DX, and try to ease out the implementation details. For example, users could keep using the semantic `import/order` without ever knowing the underlying plugin has migrated twice to `eslint-plugin-i` and then to `eslint-plugin-import-x`. User are also not forced to migrate to the implicit `i/order` halfway only because we swapped the implementation to a fork.
+>
+> That said, it's probably still not a good idea. You might not want to doing this if you are maintaining your own eslint config.
+>
+> Feel free to open issues if you want to combine this config with some other config presets but faced naming collisions. I am happy to figure out a way to make them work. But at this moment I have no plan to revert the renaming.
+
+Since v2.9.0, this preset will automatically rename the plugins also for your custom configs. You can use the original prefix to override the rules directly.
+
 ### Rules Overrides
 
 Certain rules would only be enabled in specific files, for example, `ts/*` rules would only be enabled in `.ts` files and `vue/*` rules would only be enabled in `.vue` files. If you want to override the rules, you need to specify the file extension:
@@ -349,7 +355,7 @@ export default kirklin(
 );
 ```
 
-We also provided a `overrides` options in each integration to make it easier:
+We also provided the `overrides` options in each integration to make it easier:
 
 ```js
 // eslint.config.js
@@ -374,16 +380,72 @@ export default kirklin({
 });
 ```
 
+### Config Composer
+
+Since v2.10.0, the factory function `kirklin()` returns a [`FlatConfigComposer` object from `eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils#composer) where you can chain the methods to compose the config even more flexibly.
+
+```js
+// eslint.config.js
+import kirklin from "@kirklin/eslint-config";
+
+export default kirklin()
+  .prepend(
+    // some configs before the main config
+  )
+  // overrides any named configs
+  .override(
+    "kirklin/imports",
+    {
+      rules: {
+        "import/order": ["error", { "newlines-between": "always" }],
+      }
+    }
+  )
+  // rename plugin prefixes
+  .renamePlugins({
+    "old-prefix": "new-prefix",
+    // ...
+  });
+// ...
+```
+
+### Vue
+
+Vue support is detected automatically by checking if `vue` is installed in your project. You can also explicitly enable/disable it:
+
+```js
+// eslint.config.js
+import kirklin from "@kirklin/eslint-config";
+
+export default kirklin({
+  vue: true
+});
+```
+
+#### Vue 2
+
+We have limited support for Vue 2 (as it's already [reached EOL](https://v2.vuejs.org/eol/)). If you are still using Vue 2, you can configure it manually by setting `vueVersion` to `2`:
+
+```js
+// eslint.config.js
+import kirklin from "@kirklin/eslint-config";
+
+export default kirklin({
+  vue: {
+    vueVersion: 2
+  },
+});
+```
+
+As it's in maintenance mode, we only accept bug fixes for Vue 2. It might also be removed in the future when `eslint-plugin-vue` drops support for Vue 2. We recommend upgrading to Vue 3 if possible.
+
 ### Optional Configs
 
 We provide some optional configs for specific use cases, that we don't include their dependencies by default.
 
 #### Formatters
 
-> [!WARNING]
-> Experimental feature, changes might not follow semver.
-
-Use external formatters to format files that ESLint cannot handle yet (`.css`, `.html`, etc). Powered by [`eslint-plugin-format`](https://github.com/kirklin/eslint-plugin-format).
+Use external formatters to format files that ESLint cannot handle yet (`.css`, `.html`, etc). Powered by [`eslint-plugin-format`](https://github.com/antfu/eslint-plugin-format).
 
 ```js
 // eslint.config.js
@@ -455,6 +517,44 @@ Running `npx eslint` should prompt you to install the required dependencies, oth
 npm i -D eslint-plugin-svelte
 ```
 
+#### Astro
+
+To enable astro support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import kirklin from "@kirklin/eslint-config";
+
+export default kirklin({
+  astro: true,
+});
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-astro
+```
+
+#### Solid
+
+To enable Solid support, you need to explicitly turn it on:
+
+```js
+// eslint.config.js
+import kirklin from "@kirklin/eslint-config";
+
+export default kirklin({
+  solid: true,
+});
+```
+
+Running `npx eslint` should prompt you to install the required dependencies, otherwise, you can install them manually:
+
+```bash
+npm i -D eslint-plugin-solid
+```
+
 #### UnoCSS
 
 To enable UnoCSS support, you need to explicitly turn it on:
@@ -480,9 +580,9 @@ This config also provides some optional plugins/rules for extended usage.
 
 #### `perfectionist` (sorting)
 
-This plugin [`eslint-plugin-perfectionist`](https://github.com/azat-io/eslint-plugin-perfectionist) allows you to sorted object keys, imports, etc, with auto-fix.
+This plugin [`eslint-plugin-perfectionist`](https://github.com/azat-io/eslint-plugin-perfectionist) allows you to sort object keys, imports, etc, with auto-fix.
 
-The plugin is installed but no rules are enabled by default.
+The plugin is installed, but no rules are enabled by default.
 
 It's recommended to opt-in on each file individually using [configuration comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1).
 
@@ -493,7 +593,6 @@ const objectWantedToSort = {
   b: 1,
   c: 3,
 };
-/* eslint perfectionist/sort-objects: "off" */
 ```
 
 ### Type Aware Rules
@@ -511,6 +610,21 @@ export default kirklin({
 });
 ```
 
+### Editor Specific Disables
+
+Some rules are disabled when inside ESLint IDE integrations, namely [`unused-imports/no-unused-imports`](https://www.npmjs.com/package/eslint-plugin-unused-imports) [`test/no-only-tests`](https://github.com/levibuzolic/eslint-plugin-no-only-tests)
+
+This is to prevent unused imports from getting removed by the IDE during refactoring to get a better developer experience. Those rules will be applied when you run ESLint in the terminal or [Lint Staged](#lint-staged). If you don't want this behavior, you can disable them:
+
+```js
+// eslint.config.js
+import kirklin from "@kirklin/eslint-config";
+
+export default kirklin({
+  isInEditor: false
+});
+```
+
 ### Lint Staged
 
 If you want to apply lint and auto-fix before every commit, you can add the following to your `package.json`:
@@ -537,12 +651,12 @@ npx simple-git-hooks
 
 ## View what rules are enabled
 
-I built a visual tool to help you view what rules are enabled in your project and apply them to what files, [eslint-flat-config-viewer](https://github.com/kirklin/eslint-flat-config-viewer)
+I built a visual tool to help you view what rules are enabled in your project and apply them to what files, [@eslint/config-inspector](https://github.com/eslint/config-inspector)
 
 Go to your project root that contains `eslint.config.js` and run:
 
 ```bash
-npx eslint-flat-config-viewer
+npx @eslint/config-inspector
 ```
 
 ## Versioning Policy