@shayanthenerd/eslint-config 0.17.0 → 0.20.0

package/README.md

@@ -1,26 +1,21 @@
-# @shayanthenerd/eslint-config    [![NPM Version](https://img.shields.io/npm/v/@shayanthenerd/eslint-config?label=&logo=npm&logoColor=EEEEEE&labelColor=545A61&color=545A61&registry_uri=https://registry.npmjs.com/@shayanthenerd/eslint-config&link=https://github.com/ShayanTheNerd/eslint-config)](https://www.npmjs.com/package/@shayanthenerd/eslint-config) [![License MIT](https://img.shields.io/badge/License-MIT-blue.svg?labelColor=545A61&color=545A61)](https://github.com/ShayanTheNerd/eslint-config/blob/main/LICENSE) [![Netlify Status](https://api.netlify.com/api/v1/badges/8ed76fdd-5aa7-446a-89fa-c916f8cce0de/deploy-status)](https://eslint-config.shayan-zamani.me)
+# @shayanthenerd/eslint-config   [![license-badge]][license] [![npm-version-badge]][npmx] [![jsr-version-badge]][jsr]
 
-A modern, flexible ESLint configuration for enforcing best practices and maintaining a consistent coding style.
+ESLint configuration for enforcing best practices and maintaining a consistent coding style. [Explore configurations][online-preview]!
 
-- **Performant**: Powered by [OXLint (OXC Linter)](https://oxc.rs/docs/guide/usage/linter) for rapid linting
-- **Flat Config**: Type-safe [ESLint Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files) with `extends` and `overrides` support
-- **Comprehensive**: Dependency detection with support for TypeScript, Astro, Vue & Nuxt, Tailwind, Storybook, Vitest & Playwright, and more
-- **Automatic Formatting**: Fine-grained control over formatting with [ESLint Stylistic](https://eslint.style), eliminating the need for Prettier
-- **Smart Defaults**: Respects your _.gitignore_ file and provides reasonable, opinionated, yet [highly customizable](#customization) defaults
-- **Developer-friendly**: Easy to use and well-documented with JSDoc
-- **Modern**: Requires Node.js v20.12.0+ and ESLint v9.28.0+ (ESM-only)
-
-> [!NOTE]
-> This configuration is designed with a flexible API for easy customization. However, it remains a **personal config**. While its primary goal is to enforce best practices and maintain code consistency, some rules—particularly stylistic ones—are rather opinionated. <br /> If the available customization and override options still don't meet your requirements, feel free to fork the project and tailor it to your needs.
+- **Flexible**: [Highly-customizable options](#customization) and configurations with sensible defaults.
+- **Smart**: Context-aware linting with [automatic dependency detection](#automatic-dependency-detection) and _.gitignore_ recognition.
+- **Comprehensive**: [Supports popular plugins](#plugin-support) for TypeScript, Astro, Vue & Nuxt, Tailwind, Zod, Vitest, Markdown, and more.
+- **Type-safe**: [Fully-typed and well-documented API](#api-reference) with `overrides` support for every built-in configuration object.
+- **Modern**: Requires ESLint ^10.4.0 and Node.js ^20.19.0 (ESM-only)
 
 ## Table of Contents
+- [Plugin Support](#plugin-support)
 - [Installation and Configuration](#installation-and-configuration)
+- [Customization](#customization)
 - [Automatic Dependency Detection](#automatic-dependency-detection)
+- [Framework and Tool Integrations](#framework-and-tool-integrations)
+- [IDE Support](#ide-support)
 - [Formatting](#formatting)
-- [VS Code Integration](#vs-code-integration)
-- [Customization](#customization)
-  - [OXLint](#oxlint)
-  - [ESLint](#eslint)
 - [API Reference](#api-reference)
 - [Versioning Policy](#versioning-policy)
 - [Roadmap to v1.0.0](#roadmap-to-v100)
@@ -28,170 +23,216 @@ A modern, flexible ESLint configuration for enforcing best practices and maintai
 - [Credits](#credits)
 - [License](#license)
 
-## Installation and Configuration
-1. Install the package:
-```shell
-npm i -D @shayanthenerd/eslint-config
-# or
-bun i -d @shayanthenerd/eslint-config
-# or
-pnpm i -D @shayanthenerd/eslint-config oxlint
-```
+## Plugin Support
+Legend:
+- ✅ Supported
+- ⌛️ In progress
+- ◻️ Enabled by default
+- ⬛ Disabled by default
+- 🔎 [Automatically detected](#automatic-dependency-detection) (`autoDetectDeps: true`)
+
+| Category                                                     | Support | Activation |
+| :----------------------------------------------------------- | :-----: | :----: |
+| **Languages**                                                |         |        |
+| [JavaScript][eslint]                                         |    ✅    |   ◻️    |
+| [TypeScript][plugin-ts]                                      |    ✅    |   🔎    |
+| [Markdown][plugin-md]                                        |    ✅    |   ◻️    |
+| [HTML][plugin-html]                                          |    ✅    |   ⬛    |
+| [CSS][plugin-css]                                            |    ✅    |   ⬛    |
+| **Formatting**                                               |         |        |
+| [Stylistic][plugin-stylistic]                                |    ✅    |   ◻️    |
+| [Perfectionist][plugin-perfectionist]                        |    ✅    |   ◻️    |
+| **Frameworks**                                               |         |        |
+| [Astro][plugin-astro] ([JSX accessibility][plugin-jsx-a11y]) |    ✅    |   🔎    |
+| [React][plugin-react] ([hooks][plugin-react-hooks])          |    ⌛️    |   N/A  |
+| [Next][plugin-next]                                          |    ⌛️    |   N/A  |
+| [Vue & Nuxt][plugin-vue] ([accessibility][plugin-vue-a11y])  |    ✅    |   🔎    |
+| [Tailwind][plugin-tailwind]                                  |    ✅    |   ⬛    |
+| **Testing Tools**                                            |         |        |
+| [Storybook][plugin-storybook]                                |    ✅    |   🔎    |
+| [Vitest][plugin-vitest]                                      |    ✅    |   🔎    |
+| [Cypress][plugin-cypress]                                    |    ✅    |   🔎    |
+| [Playwright][plugin-playwright]                              |    ✅    |   🔎    |
+| **Miscellaneous**                                            |         |        |
+| [_package.json_][plugin-package-json]                        |    ✅    |   ◻️    |
+| [promises][plugin-promise]                                   |    ✅    |   ◻️    |
+| [Imports][plugin-import-x]                                   |    ✅    |   ◻️    |
+| [Zod][plugin-zod]                                            |    ✅    |   🔎    |
+| [Node][plugin-node]                                          |    ⌛️    |   N/A  |
+| [Unicorn][plugin-unicorn]                                    |    ⌛️    |   N/A  |
 
-This will install OXLint along with all the necessary ESLint plugins and parsers. However, if you're using PNPM, you must install `oxlint` separately.
-
-2. Create an ESLint config file (_eslint.config.js_) at the root of your project:
-```js
-import { defineConfig } from '@shayanthenerd/eslint-config';
+## Installation and Configuration
+1. Install the package and ESLint as dev dependencies:
+   ```shell
+   npm i -D @shayanthenerd/eslint-config eslint
+   ```
+
+2. Create an ESLint configuration file (_eslint.config.js_) at the root of your project:
+   ```js title="eslint.config.js"
+   import { defineConfig } from '@shayanthenerd/eslint-config';
+
+   export default defineConfig();
+   ```
+
+   Note: TypeScript configuration files (_eslint.config.ts_) are also supported. Node.js versions below v22.18.0 may require [additional setup][eslint-config-ts-setup].
+
+3. Add the following scripts to your _package.json_:
+   ```json title="package.json"
+   {
+     "scripts": {
+       "lint:inspect": "npx @eslint/config-inspector",
+       "lint": "eslint --fix --cache --cache-location='node_modules/.cache/.eslintcache'"
+     }
+   }
+   ```
 
-export default defineConfig();
-```
+---
 
-You can also use a TypeScript file (_eslint.config.ts_). Depending on your Node.js version, [additional setup](https://eslint.org/docs/latest/use/configure/configuration-files#typescript-configuration-files) may be required.
+After installation:
+- Use `npm run lint` to lint and fix files.
+- Use `npm run lint:inspect` to see a visual breakdown of your configuration.
+- See [IDE Support](#ide-support) for editor integration.
+- See [Customization](#customization) for advanced configuration.
+- See [Formatting](#formatting) for formatting options and Prettier integration.
 
-If you're using Nuxt, install [@nuxt/eslint](https://eslint.nuxt.com) as a dev dependency:
-```shell
-npm i -D @nuxt/eslint
-```
+## Customization
+`defineConfig()` supports both simple and advanced use cases:
+```js title="eslint.config.js"
+import eslintPluginYaml from 'eslint-plugin-yaml';
+import * as eslintPluginRegexp from 'eslint-plugin-regexp';
 
-Then, update your ESLint config file:
-```js
 import { defineConfig } from '@shayanthenerd/eslint-config';
 
-import eslintConfigNuxt from './.nuxt/eslint.config.mjs';
-
-const eslintConfig = defineConfig();
-
-export default eslintConfigNuxt(eslintConfig);
-```
+// Use the default configuration:
+export default defineConfig();
 
-> [!NOTE]
-> The Nuxt config relies on the Vue config, so make sure it's enabled (either automatically or manually).
+// Customize the built-in configurations:
+export default defineConfig({
+  autoDetectDeps: false,
+  configs: {
+    stylistic: false,
+    markdown: {
+      language: 'commonmark',
+    },
+  },
+});
 
-3. If you're not using OXLint, set `configs.oxlint` to `false` in your ESLint config and skip this step. Otherwise, create an OXLint config file (_.oxlintrc.json_) in the root of your project:
-```jsonc
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json", // Optional
-
-  "extends": ["./node_modules/@shayanthenerd/eslint-config/dist/oxlint.config.jsonc"],
-
-  /* Customize based on your development environment. */
-  "env": {
-    "worker": false,
-    "commonjs": false,
-    "bun": false,
-    "deno": false,
-    "node": true,
-    "nodeBuiltin": true,
-    "browser": true,
-    "serviceworker": false,
-    "sharedWorker": false,
-    "webextension": false,
-    "audioWorklet": false,
-    "vitest": true,
-    "vue": true,
-    "astro": true
+// Use custom configuration objects:
+export default defineConfig([
+  {
+    files: ['**/*.yaml', '**/*.yml'],
+    ignores: ['**/*.schema.yaml', '**/*.schema.yml'],
+    extends: [eslintPluginYaml.configs.recommended],
   },
+  eslintPluginRegexp.configs['flat/recommended'],
+]);
 
-  "categories": {
-    "correctness": "error",
-    "suspicious": "error",
-    "restriction": "error",
-    "pedantic": "error",
-    "perf": "warn",
-    "style": "warn",
-    "nursery": "error"
-  }
-}
+// Customize the built-in configurations and use custom configuration objects:
+export default defineConfig(
+  {
+    autoDetectDeps: 'verbose',
+    configs: {
+      typescript: {
+        typeDefinitionStyle: 'type',
+        overrides: {
+          rules: {
+            '@typescript-eslint/explicit-module-boundary-types': 'off',
+          },
+        },
+      },
+    },
+  },
+  [
+    {
+      files: ['**/*.yaml', '**/*.yml'],
+      ignores: ['**/*.schema.yaml', '**/*.schema.yml'],
+      extends: [eslintPluginYaml.configs.recommended],
+    },
+    eslintPluginRegexp.configs['flat/recommended'],
+  ],
+);
 ```
 
-Due to [the limitation of OXLint](https://oxc.rs/docs/guide/usage/linter/nested-config#extending-configuration-files), only `rules`, `plugins`, and `overrides` can be extended. Check out [OXLint config reference](https://oxc.rs/docs/guide/usage/linter/config-file-reference) for more details.
+Every built-in configuration accepts an `overrides` option. These values are merged into the generated configuration and take precedence over the defaults.
+```ts
+import type { ESLint, Linter } from 'eslint';
 
-4. Add the following scripts to your _package.json_ file:
-```json
-{
-  "scripts": {
-    "lint:inspect": "npx @eslint/config-inspector",
-    "lint:oxlint": "oxlint --fix",
-    "lint:eslint": "eslint --fix --cache --cache-location='node_modules/.cache/.eslintcache'",
-    "lint": "npm run lint:oxlint && npm run lint:eslint"
-  }
+interface Overrides {
+  name?: string,
+  files?: (string | string[])[],
+  ignores?: string[],
+  plugins?: Record<string, ESLint.Plugin>,
+  languageOptions?: Linter.Config['languageOptions'],
+  settings?: Record<string, unknown>,
+  rules?: ConfigRules, // The available rules in the current configuration object
 }
 ```
 
----
-
-That's it! You can now run OXLint and ESLint in your project:
-```shell
-npm run lint
-```
-
-To get a visual breakdown of your configuration, run:
-```shell
-npm run lint:inspect
-```
-
 ## Automatic Dependency Detection
-This package automatically detects dependencies in your project and enables the corresponding ESLint configurations for them. This is powered by [local-pkg](https://github.com/antfu-collective/local-pkg), which scans your _node_modules_ directory instead of _package.json_. <br />
-> [!IMPORTANT]
-> This behavior is particularly noticeable with package managers that use a flat _node_modules_ structure, such as **NPM** or **Bun**. <br />
-A concrete example is `eslint-plugin-storybook`, which is a dependency of this package. Since the plugin transitively depends on `storybook`, NPM and Bun hoist `storybook` to the root of your _node_modules_. As a result, the ESLint configuration for `storybook` will be automatically enabled, even if you haven't explicitly installed it. <br />
-Using a package manager with strict dependency resolution, such as **PNPM**, prevents this issue by hiding transitive dependencies from the root of your _node_modules_.
+[local-pkg][local-pkg] is used to detect installed dependencies and automatically enable the relevant integrations. Package managers that hoist transitive dependencies (such as NPM and Bun) may sometimes cause an integration to get enabled unexpectedly. This is because **_local-pkg_ scans _node_modules_ instead of _package.json_.**
 
-To opt out of this behavior, you can either set `autoDetectDeps: false` in the options object or explicitly disable any unwanted configurations that were automatically enabled.
+PNPM's strict dependency resolution avoids this issue.
 
-Unlike other plugins, the configuration for Tailwind isn't automatically enabled upon dependency detection, because you must explicitly provide the path to your Tailwind entry point (config file), or the ESLint configuration won't work as expected.
+> [!NOTE]
+> For example, `eslint-plugin-storybook` depends on `storybook`, which is hoisted by NPM and Bun. As a result, the integration for `storybook` will be enabled automatically, even if you haven't explicitly installed it.
 
-Stylistic, Perfectionist, ImportX, and core (JavaScript) rules are enabled by default.
+To opt out of this behavior, either [globally disable automatic dependency detection](#customization) or manually disable the unwanted integrations that were enabled automatically.
 
-## Formatting
-This config uses [ESLint Stylistic](https://eslint.style) to format JavaScript and TypeScript files (`?([mc])[jt]s?(x)`) as well as Astro (similar to JSX/TSX) and the `<script>` blocks in Vue components. HTML and the `<template>` blocks in Vue components are formatted with [html-eslint](https://html-eslint.org) and [eslint-plugin-vue](https://eslint.vuejs.org), respectively. For other files such as CSS, JSON, and Markdown, you'll need Prettier. To make this easier, a customizable [shared Prettier configuration](https://prettier.io/docs/sharing-configurations) is provided. Here's how to set it up:
+## Framework and Tool Integrations
+### Tailwind
+The Tailwind integration isn't automatically enabled because ESLint needs to know where to locate your Tailwind configuration.
+```js title="eslint.config.js"
+import { defineConfig } from '@shayanthenerd/eslint-config';
 
-1. Install Prettier:
-```shell
-npm i -D prettier
+export default defineConfig({
+  configs: {
+    tailwind: {
+      /* Either option is sufficient, but both can be provided. */
+      config: './tailwind.config.js',
+      entryPoint: './app/assets/styles/app.css',
+    },
+  },
+});
 ```
 
-2. Create a Prettier config file in the root of your project (_prettier.config.js_):
-```js
-import prettierConfig from '@shayanthenerd/eslint-config/prettier';
-
-/** @type {import('prettier').Config} */
-export default {
-  ...prettierConfig,
-  semi: false, // Override `semi` from the shared config
-};
+For editor integration, to avoid inconsistent diagnostics and auto-fixes from the [Tailwind CSS IntelliSense VS Code extension][extension-tailwind], add the following settings to _.vscode/settings.json_:
+```json title=".vscode/settings.json"
+{
+  "tailwindCSS.lint.cssConflict": "ignore",
+  "tailwindCSS.lint.recommendedVariantOrder": "ignore",
+  "tailwindCSS.lint.suggestCanonicalClasses": "ignore",
+
+  "eslint.rules.customizations": [
+    { "rule": "better-tailwindcss/*", "severity": "off", "fixable": true },
+    { "rule": "better-tailwindcss/no-restricted-classes", "severity": "warn", "fixable": true },
+    { "rule": "better-tailwindcss/no-conflicting-classes", "severity": "error", "fixable": false },
+    { "rule": "better-tailwindcss/no-unknown-classes", "severity": "warn", "fixable": false }
+  ]
+}
 ```
 
-Or if you prefer using TypeScript (_prettier.config.ts_):
-```ts
-import type { Config } from 'prettier';
+### Nuxt
+Nuxt support is already included through the Vue integration, so you don’t need to install or configure [@nuxt/eslint][eslint-nuxt] manually. If you need additional rules tailored to Nuxt, refer to the plugin’s documentation for setup instructions.
 
-import prettierConfig from '@shayanthenerd/eslint-config/prettier';
+> [!TIP]
+> `configs.nuxt` only includes options for Nuxt Image, Nuxt UI, and the `<Icon>` component. Vue's rules and `overrides` can be configured via `configs.vue`.
 
-export default {
-  ...prettierConfig,
-  semi: true, // Override `semi` from the shared config
-} satisfies Config;
-```
+### Markdown
+Markdown linting is powered by [@eslint/markdown][plugin-md].
 
-3. To prevent conflicts with ESLint, Prettier should be configured to only format files other than JavaScript, TypeScript, Astro, HTML, and Vue. Hence, add the following script to your _package.json_ file:
-```json
-{
-  "scripts": {
-    "format": "prettier --write . '!**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx,html,vue,astro}' --cache"
-  }
-}
-```
+By default, the plugin uses GitHub Flavored Markdown (GFM). You can [switch to CommonMark](#customization) if you prefer, but rules related to tables, label references, and other GFM syntax will be disabled because CommonMark doesn't support them.
 
-## VS Code Integration
-Install VS Code extensions for [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), [OXLint](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode), and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). Then, add the following in the _.vscode/settings.json_ file of your project:
-```jsonc
+> [!NOTE]
+> Fenced code blocks inside Markdown files are not linted by @eslint/markdown.
+
+## IDE Support
+Install the VS Code extensions for [ESLint][extension-eslint] and [Prettier][extension-prettier]. Then add the following in _.vscode/settings.json_:
+```jsonc title=".vscode/settings.json"
 {
   /* Enforce Unix-like line endings (LF). */
   "files.eol": "\n",
 
-  /* Enforce either tabs or spaces for indentation. */
+  /* Enforce 2 spaces for indentation. */
   "editor.tabSize": 2,
   "editor.insertSpaces": true,
   "editor.detectIndentation": false,
@@ -202,35 +243,27 @@ Install VS Code extensions for [ESLint](https://marketplace.visualstudio.com/ite
     "source.organizeImports": "never",
     "source.removeUnusedImports": "never",
 
-    /* Apply OXLint and ESLint automatic fixes on file save. */
-    "source.fixAll.oxc": "explicit",
+    /* Apply ESLint fixes when saving files. */
     "source.fixAll.eslint": "explicit"
   },
-	"oxc.lint.run": "onSave",
-	"eslint.run": "onSave",
-  "editor.formatOnSave": true,
-	"eslint.format.enable": true,
 
-  /* Format and lint JavaScript, TypeScript, HTML, and Vue files with ESLint, while everything else is formatted with Prettier. */
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "[javascript][typescript][javascriptreact][typescriptreact][html][vue][astro]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  },
+  "eslint.run": "onSave",
+  "eslint.format.enable": true,
   "eslint.validate": [
     "javascript",
     "typescript",
     "javascriptreact",
     "typescriptreact",
+    "json",
+    "markdown",
     "html",
     "css",
     "tailwindcss",
-    "vue",
-    "astro"
+    "astro",
+    "vue"
   ],
 
-  /* Adjust these based on the features you're using to silently auto-fix the stylistic rules in your IDE. */
-  "tailwindCSS.lint.cssConflict": "ignore", // Only if you're using the Tailwind config
-	"tailwindCSS.lint.recommendedVariantOrder": "ignore", // Only if you're using the Tailwind config
+  /* Adjust these based on the features you're using to silently auto-fix the stylistic rules. */
   "eslint.rules.customizations": [
     { "rule": "*styl*", "severity": "off", "fixable": true },
     { "rule": "*sort*", "severity": "off", "fixable": true },
@@ -241,214 +274,313 @@ Install VS Code extensions for [ESLint](https://marketplace.visualstudio.com/ite
     { "rule": "*order-*", "severity": "off", "fixable": true },
     { "rule": "*newline*", "severity": "off", "fixable": true },
     { "rule": "*attribute*", "severity": "off", "fixable": true },
+    { "rule": "package-json/order-properties", "severity": "off", "fixable": true },
     { "rule": "vue/max-len", "severity": "off", "fixable": true },
     { "rule": "vue/comma-dangle", "severity": "off", "fixable": true },
-    { "rule": "vue/space-in-parens", "severity": "off", "fixable": true },
-    { "rule": "better-tailwindcss/*", "severity": "off", "fixable": true },
-    { "rule": "better-tailwindcss/no-restricted-classes", "severity": "error", "fixable": true },
-    { "rule": "better-tailwindcss/no-conflicting-classes", "severity": "error", "fixable": false },
-    { "rule": "better-tailwindcss/no-unregistered-classes", "severity": "error", "fixable": false }
+    { "rule": "vue/space-in-parens", "severity": "off", "fixable": true }
   ]
 }
 ```
 
-## Customization
-### OXLint
-Since OXLint and ESLint use separate config files, customizations made in your ESLint config will not apply to OXLint. However, you can still customize OXLint rules in your _.oxlintrc.json_ file. Here's an example:
-```jsonc
-{
-  /* Base configuration */
+> [!TIP]
+> These settings match the default behavior of this configuration. If you've customized any formatting or stylistic rules, update the corresponding editor settings to keep them consistent.
 
-  "rules": {
-    /* Globally override rules. */
-    "oxlint/no-named-as-default-member": "warn"
-  },
+## Formatting
+This configuration uses [ESLint Stylistic][plugin-stylistic] to format:
+- JavaScript and TypeScript (_js_, _cjs_, _mjs_, _jsx_, _ts_, _cts_, _mts_, _tsx_),
+- Astro (similar to _jsx_/_tsx_), and
+- Vue's `<script>` blocks.
 
-  "overrides": [
-    /* Override rules for specific files. */
-    {
-      "files": ["app/**/*.tsx"],
-      "ignores": ["app/app.tsx"],
-      "rules": {
-        "oxlint/max-depth": ["error", { "max": 5 }],
-        "oxlint/explicit-function-return-type": "off"
-      }
-    }
-  ],
+HTML and Vue's `<template>` blocks are formatted with [@html-eslint/eslint-plugin][plugin-html] and [eslint-plugin-vue][plugin-vue], respectively.
 
-  /* OXLint respects the ignore patterns defined in `.gitignore` and `.eslintignore` files by default. */
-  "ignorePatterns": ["**/*.min.*"]
+For file types not handled by ESLint Stylistic—such as CSS, JSON, Yaml, and Markdown—you can use Prettier. To simplify the setup, this package also provides a customizable [shared Prettier configuration][prettier-shared-config].
+
+1. Install Prettier as a dev dependency:
+   ```shell
+   npm i -D prettier
+   ```
+
+2. Create a Prettier config file in the root of your project (_prettier.config.js_):
+   ```js title="prettier.config.js"
+   import prettierConfig from '@shayanthenerd/eslint-config/prettier';
+
+   /** @type {import('prettier').Config} */
+   export default {
+     ...prettierConfig,
+     semi: false, // Override `semi` from the shared config
+   };
+   ```
+
+   Or if you prefer using TypeScript (_prettier.config.ts_):
+   ```ts title="prettier.config.ts"
+   import type { Config } from 'prettier';
+
+   import prettierConfig from '@shayanthenerd/eslint-config/prettier';
+
+   export default {
+     ...prettierConfig,
+     semi: true, // Override `semi` from the shared config
+   } satisfies Config;
+   ```
+
+### Using ESLint Stylistic with Prettier
+In this setup, Prettier formats everything that ESLint Stylistic doesn't. To prevent overlaps and potential race conditions, Prettier should only target files that ESLint Stylistic doesn't format.
+
+_package.json_:
+```json title="package.json"
+{
+  "scripts": {
+    "format": "prettier --write . '!**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx,html,vue,astro}' --cache"
+  }
 }
 ```
-
-### ESLint
-`defineConfig` takes the `options` object as the first argument. `options` is thoroughly documented with JSDoc and provides many options for rule customizations. In addition, each config object in `options.configs` accepts an `overrides` option:
-```ts
-interface Overrides {
-  name: '',
-  files: [],
-  ignores: [],
-  plugins: {},
-  settings: {},
-  languageOptions: {
-    parser: {},
-    globals: {},
+_.vscode/settings.json_:
+```json title=".vscode/settings.json"
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "[javascript][typescript][javascriptreact][typescriptreact][html][vue][astro][{**/package.json}]": {
+  "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
-  rules: {},
 }
 ```
 
-`overrides` is merged with the default config, taking precedence over its properties. However, there is no guarantee that the resulting configuration works correctly — it depends on the options you provide.
-
-`defineConfig` also accepts any number of custom ESLint Flat Configs (_eslint.config.js_):
-```js
-import eslintPluginYaml from 'eslint-plugin-yaml';
-import * as eslintPluginRegexp from 'eslint-plugin-regexp';
-import { defineConfig } from '@shayanthenerd/eslint-config';
-
-export default defineConfig(
-  /* The options object: */
-  {
-    env: 'bun',
-    configs: {
-      typescript: {
-        typeDefinitionStyle: 'type',
-        overrides: {
-          rules: {
-            '@typescript-eslint/no-unsafe-type-assertion': 'off',
-          },
-        },
-      },
-    },
-  },
+### Using Prettier Alone
+If you prefer to use Prettier as the only formatter, [disable the stylistic configuration](#customization) and let Prettier handle all formatting. Note that **this approach provides less granular control over the formatting options**.
 
-  /* ESLint Flat Configs: */
-  {
-    files: ['**/*.yaml', '**/*.yml'],
-    ignores: ['**/*.schema.yaml', '**/*.schema.yml'],
-    extends: [pluginYaml.configs.recommended],
-  },
-  regexpPlugin.configs['flat/recommended'],
-);
+_package.json_:
+```json title="package.json"
+{
+  "scripts": {
+    "format": "prettier --write . --cache"
+  }
+}
 ```
+_.vscode/settings.json_:
+```json title=".vscode/settings.json"
+{
+  "eslint.format.enable": false,
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "never"
+  }
+}
+```
+
+When using this approach:
+- Avoid running `lint` and `format` scripts on the same files simultaneously.
+- Use either ESLint fixes or Prettier formatting when saving files, but not both.
 
 ## API Reference
 <details>
-  <summary>The API reference</summary>
-  Some types are omitted or aliased for brevity.
+  <summary>
+    <!-- eslint-disable-next-line markdown/no-html -->
+    The API reference of the <code>options</code> object passed to <code>defineConfig</code>
+  </summary><br />
 
+  <small>Some types are omitted or aliased for brevity.</small>
+
+  <!-- START_AUTO-GENERATED_API_REFERENCE -->
   ```ts
+  import type { ESLint, Linter } from 'eslint';
+
+  type VueAttributeCategory =
+    | 'SLOT'
+    | 'EVENTS'
+    | 'GLOBAL'
+    | 'UNIQUE'
+    | 'CONTENT'
+    | 'DEFINITION'
+    | 'OTHER_ATTR'
+    | 'ATTR_STATIC'
+    | 'ATTR_DYNAMIC'
+    | 'CONDITIONALS'
+    | 'LIST_RENDERING'
+    | 'TWO_WAY_BINDING'
+    | 'OTHER_DIRECTIVES'
+    | 'RENDER_MODIFIERS'
+    | 'ATTR_SHORTHAND_BOOL';
+
+  interface Overrides {
+    name?: string,
+    files?: (string | string[])[],
+    ignores?: string[],
+    plugins?: Record<string, ESLint.Plugin>,
+    languageOptions?: Linter.Config['languageOptions'],
+    settings?: Record<string, unknown>,
+    rules?: ConfigRules, // The available rules in the current configuration object
+  }
+
   interface Options {
     autoDetectDeps?: boolean | 'verbose',
+    env?: 'browser' | 'bun' | 'deno' | 'node',
     gitignore?: false | string,
     packageDir?: string,
-    env?: 'bun' | 'node',
-    tsConfig?: {
-      rootDir: string,
+    tsConfig?: false | {
       filename?: string,
+      rootDir: string,
     },
 
-    global?: {
-      name?: string,
+    project?: {
       basePath?: string,
-      ignores?: string[],
       globals?: {
-        worker?: boolean,
-        commonjs?: boolean,
+        astro?: boolean,
+        audioWorklet?: boolean,
+        browser?: boolean,
         bun?: boolean,
+        commonjs?: boolean,
         deno?: boolean,
         node?: boolean,
         nodeBuiltin?: boolean,
-        browser?: boolean,
         serviceworker?: boolean,
         sharedWorker?: boolean,
-        webextension?: boolean,
-        audioWorklet?: boolean,
         vitest?: boolean,
         vue?: boolean,
-        astro?: boolean,
-        custom?: {
-          [key: string]: boolean | 'off' | 'readonly' | 'readable' | 'writable' | 'writeable',
-        },
-      }
+        webextension?: boolean,
+        worker?: boolean,
+        custom?: Record<string, 'off' | boolean | 'readable' | 'readonly' | 'writable' | 'writeable'>,
+      },
+      ignores?: string[],
       linterOptions?: {
         noInlineConfig?: boolean,
-        reportUnusedInlineConfigs?: 'error' | 'off' | 'warn',
-        reportUnusedDisableDirectives?: 'error' | 'off' | 'warn',
+        reportUnusedDisableDirectives?: 'off' | 'warn' | 'error',
+        reportUnusedInlineConfigs?: 'off' | 'warn' | 'error',
       },
-      settings?: {
-        [name: string]: unknown,
-      }
+      name?: string,
       rules?: Linter.RulesRecord,
+      settings?: Record<string, unknown>,
     },
 
     configs?: {
-      oxlint?: false | string,
+      astro?: boolean | {
+        overrides?: Overrides,
+      },
       base?: {
+        functionStyle?: 'expression' | 'declaration',
         maxDepth?: number,
         maxNestedCallbacks?: number,
         preferNamedExports?: boolean,
-        functionStyle?: 'declaration' | 'expression',
-        overrides?: {},
+        overrides?: Overrides,
+      },
+      css?: boolean | {
+        allowedRelativeFontUnits?: (
+          | '%'
+          | 'ch'
+          | 'em'
+          | 'ex'
+          | 'ic'
+          | 'lh'
+          | 'cap'
+          | 'rch'
+          | 'rem'
+          | 'rex'
+          | 'ric'
+          | 'rlh'
+          | 'rcap'
+        )[],
+        useBaseline?: false | number | 'newly' | 'widely',
+        overrides?: Overrides,
+      },
+      html?: boolean | {
+        idNamingConvention?: 'camelCase' | 'kebab-case' | 'PascalCase' | 'snake_case',
+        useBaseline?: false | number | 'newly' | 'widely',
+        overrides?: Overrides,
+      },
+      importX?: boolean | {
+        overrides?: Overrides,
+      },
+      markdown?: boolean | {
+        allowedHtmlTags?: string[],
+        frontmatter?: false | 'json' | 'toml' | 'yaml',
+        language?: 'gfm' | 'commonmark',
+        overrides?: Overrides,
+      },
+      nuxt?: boolean | {
+        icon?: boolean | {
+          component?: string,
+        },
+        image?: boolean,
+        ui?: boolean | {
+          prefix?: string,
+        },
+      },
+      packageJson?: boolean | {
+        overrides?: Overrides,
+      },
+      perfectionist?: boolean | {
+        sortType?: 'custom' | 'natural' | 'unsorted' | 'line-length' | 'alphabetical' | 'subgroup-order',
+        overrides?: Overrides,
+      },
+      promise?: boolean | {
+        overrides?: Overrides,
       },
       stylistic?: boolean | {
-        semi?: 'always' | 'never',
-        trailingComma?: 'always' | 'never' | 'always-multiline' | 'only-multiline',
-        memberDelimiterStyle?: 'semi' | 'comma',
-        quotes?: 'single' | 'double' | 'backtick',
-        jsxQuotes?: 'prefer-single' | 'prefer-double',
         arrowParens?: 'always' | 'as-needed',
         indent?: number,
+        jsxQuotes?: 'prefer-double' | 'prefer-single',
+        maxAttributesPerLine?: number,
         maxConsecutiveEmptyLines?: number,
         maxLineLength?: number,
-        maxAttributesPerLine?: number,
+        memberDelimiterStyle?: 'semi' | 'comma',
+        quotes?: 'double' | 'single' | 'backtick',
         selfCloseVoidHTMLElements?: 'never' | 'always',
-        overrides?: {},
-      },
-      html?: boolean | {
-        useBaseline?: number | false | 'widely' | 'newly',
-        idNamingConvention?: 'camelCase' | 'snake_case' | 'PascalCase' | 'kebab-case',
-        overrides?: {},
-      },
-      css?: boolean | {
-        useBaseline?: number | false | 'widely' | 'newly',
-        allowedRelativeFontUnits?: ('%' | 'cap' | 'ch' | 'em' | 'ex' | 'ic' | 'lh' | 'rcap' | 'rch' | 'rem' | 'rex' | 'ric' | 'rlh')[],
-        overrides?: {},
+        semi?: 'never' | 'always',
+        trailingComma?: 'never' | 'always' | 'only-multiline' | 'always-multiline',
+        overrides?: Overrides,
       },
       tailwind?: false | {
         config: string,
+        cwd?: string,
         entryPoint?: string,
+        ignoredUnknownClasses?: string[],
         multilineSort?: boolean,
-        ignoredUnregisteredClasses?: string[],
-        overrides?: {},
+        overrides?: Overrides,
       } | {
         config?: string,
+        cwd?: string,
         entryPoint: string,
+        ignoredUnknownClasses?: string[],
         multilineSort?: boolean,
-        ignoredUnregisteredClasses?: string[],
-        overrides?: {},
+        overrides?: Overrides,
+      },
+      test?: {
+        maxNestedDescribe?: number,
+        testFunction?: 'it' | 'test',
+        cypress?: boolean | {
+          overrides?: Overrides,
+        },
+        playwright?: boolean | {
+          overrides?: Overrides,
+        },
+        storybook?: boolean | {
+          overrides?: Overrides,
+        },
+        vitest?: boolean | {
+          overrides?: Overrides,
+        },
       },
       typescript?: boolean | {
         allowedDefaultProjects?: string[],
-        methodSignatureStyle?: 'property' | 'method',
-        typeDefinitionStyle?: 'interface' | 'type',
-        overrides?: {},
-      },
-      importX?: boolean | {
+        methodSignatureStyle?: 'method' | 'property',
         removeUnusedImports?: boolean,
-        overrides?: {},
-      },
-      perfectionist?: boolean | {
-        sortType?: 'custom' | 'natural' | 'alphabetical' | 'line-length' | 'unsorted',
-        overrides?: {},
+        typeDefinitionStyle?: 'type' | 'interface',
+        overrides?: Overrides,
       },
       vue?: boolean | {
         accessibility?: boolean | {
+          accessibleChildComponents?: string[],
           anchorComponents?: string[],
           imageComponents?: string[],
-          accessibleChildComponents?: string[],
         },
-        blockOrder?: (
+        allowedStyleAttributes?: ['plain' | 'module' | 'scoped', 'plain' | 'module' | 'scoped'],
+        attributeHyphenation?: 'never' | 'always',
+        attributesOrder?: (VueAttributeCategory | VueAttributeCategory[])[],
+        blockLang?: {
+          script?: 'js' | 'ts' | 'jsx' | 'tsx' | 'implicit',
+          style?: 'css' | 'scss' | 'postcss' | 'implicit',
+        },
+        blocksOrder?: (
           | 'docs'
           | 'template'
           | 'script[setup]'
@@ -458,92 +590,116 @@ export default defineConfig(
           | 'style:not([scoped])'
           | 'i18n:not([locale=en])'
         )[],
+        componentNameCaseInTemplate?: 'kebab-case' | 'PascalCase',
+        destructureProps?: 'never' | 'always' | 'only-when-assigned',
+        ignoredUndefinedComponents?: string[],
         macrosOrder?: (
           | 'definePage'
+          | 'defineEmits'
           | 'defineModel'
           | 'defineProps'
-          | 'defineEmits'
           | 'defineSlots'
           | 'defineCustom'
           | 'defineExpose'
           | 'defineOptions'
         )[],
-        attributesOrder?: RuleOptions<'vue/attributes-order'>['order'],
-        attributeHyphenation?: 'never' | 'always',
         preferVBindSameNameShorthand?: 'never' | 'always',
         preferVBindTrueShorthand?: 'never' | 'always',
-        allowedStyleAttributes?: ['module' | 'plain' | 'scoped', 'module' | 'plain' | 'scoped'],
-        blockLang?: {
-          style?: 'css' | 'implicit' | 'scss' | 'postcss',
-          script?: 'js' | 'ts' | 'jsx' | 'tsx' | 'implicit',
-        },
-        destructureProps?: 'never' | 'always',
-        componentNameCaseInTemplate?: 'PascalCase' | 'kebab-case',
-        vForDelimiterStyle?: 'in' | 'of',
-        vOnHandlerStyle?: 'inline' | 'inline-function' | ['method', 'inline' | 'inline-function'],
         restrictedElements?: (string | {
           element: string | string[],
           message: string,
         })[],
         restrictedStaticAttributes?: (string | {
-          key: string,
-          value?: string | true,
           element: string,
+          key: string,
           message: string,
+          value: true | string,
         })[],
-        ignoredUndefinedComponents?: string[],
-        overrides?: {},
-      },
-      nuxt?: boolean | {
-        image?: boolean,
-        icon?: boolean | {
-          component?: string,
-        }
-        ui?: boolean | {
-          prefix?: string,
-        }
+        vForDelimiterStyle?: 'in' | 'of',
+        overrides?: Overrides,
       },
-      test?: {
-        storybook?: boolean | {
-          overrides?: {},
-        },
-        vitest?: boolean | {
-          overrides?: {},
-        },
-        playwright?: boolean | {
-          overrides?: {},
-        },
-        cypress?: boolean | {
-          overrides?: {},
-        },
-        testFunction?: 'test' | 'it',
-        maxNestedDescribe?: number,
+      zod?: boolean | {
+        mini?: boolean,
+        overrides?: Overrides,
       },
     },
   }
   ```
+  <!-- END_AUTO-GENERATED_API_REFERENCE -->
 </details>
 
 ## Versioning Policy
-This project adheres to [The Semantic Versioning Standard](https://semver.org). However, to facilitate rapid development and fast iteration, the following changes are considered non-breaking:
-- Upgrades to dependency versions
+This project adheres to [The Semantic Versioning Standard][semver]. However, to facilitate rapid development and fast iteration, **the following changes are considered non-breaking**:
+- Updates to dependency versions
 - Modifications to rule options
 - Enabling or disabling rules and plugins
 
 Under this policy, minor updates may introduce new linting errors, which could break your project's build pipeline. To prevent this, it's recommended to use an exact version. Alternatively, you can use a tilde (`~`) version range in your _package.json_ file (e.g., `"@shayanthenerd/eslint-config": "~1.2.3"`), which will restrict updates to patches only, ensuring your project's build pipeline remains stable.
 
-You can find a list of all available versions and their changelogs on the [releases page](https://github.com/ShayanTheNerd/eslint-config/releases).
+You can find a list of all available versions and their changelogs on the [releases page][releases].
 
 ## Roadmap to v1.0.0
-- [ ] Integrate additional ESLint plugins such as [eslint-plugin-unicorn](https://github.com/sindresorhus/eslint-plugin-unicorn), [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n), [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc), etc.
-- [ ] Add support for other frameworks and file types, including Astro, React, Next.js, MDX, Markdown, JSON, etc.
-- [ ] Develop a starter wizard to automate the setup of OXLint, ESLint, Prettier, and other configurations.
+- [ ] Add integration for ESLint plugins such as [eslint-plugin-n][plugin-node], [eslint-plugin-unicorn][plugin-unicorn], and more.
+- [ ] Add support for other React, Next, Astro, and Markdown.
+- [ ] Develop an interactive starter wizard to quickly scaffold the configurations for ESLint, Prettier, etc.
 
 ## Contribution Guide
-Any form of contribution is always appreciated! Please chekc out the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+Contributions of all kinds are welcome. Please check out the [CONTRIBUTING.md][contributing] file.
 
 ## Credits
-This project was inspired by the work of [Anthony Fu](https://github.com/antfu), whose generous contributions to the JavaScript and the ESLint ecosystem were instrumental in making it possible.
+This project was inspired by the work of [Anthony Fu][antfu], whose generous contributions to the JavaScript and the ESLint ecosystem were instrumental in making it possible.
 
 ## License
-[MIT](LICENSE) License © 2025-PRESENT — [Shayan Zamani](https://github.com/ShayanTheNerd)
+[MIT][license] License © 2025-PRESENT — [Shayan Zamani][ShayanTheNerd]
+
+<!-- Badges -->
+[jsr]: https://jsr.io/badges/@shayanthenerd/eslint-config
+[jsr-version-badge]: https://jsr.io/badges/@shayanthenerd/eslint-config?logoColor=FEFEFE&labelColor=3B82F6&color=3B82F6
+[license]: ./LICENSE
+[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg?logoColor=FEFEFE&labelColor=3B82F6&color=3B82F6
+[npm-version-badge]: https://img.shields.io/npm/v/@shayanthenerd/eslint-config?label=&logo=npm&logoColor=FEFEFE&labelColor=3B82F6&color=3B82F6
+[npmx]: https://www.npmjs.com/package/@shayanthenerd/eslint-config
+
+<!-- Editor Extensions -->
+[extension-eslint]: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint
+[extension-prettier]: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
+[extension-tailwind]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss
+
+<!-- ESLint Plugins -->
+[plugin-astro]: https://ota-meshi.github.io/eslint-plugin-astro
+[plugin-css]: https://github.com/eslint/css
+[plugin-cypress]: https://github.com/cypress-io/eslint-plugin-cypress
+[plugin-html]: https://html-eslint.org
+[plugin-import-x]: https://github.com/un-ts/eslint-plugin-import-x
+[plugin-jsx-a11y]: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y
+[plugin-md]: https://github.com/eslint/markdown
+[plugin-next]: https://nextjs.org/docs/app/api-reference/config/eslint#eslint-plugin
+[plugin-node]: https://github.com/eslint-community/eslint-plugin-n
+[plugin-package-json]: https://github.com/JoshuaKGoldberg/eslint-plugin-package-json
+[plugin-perfectionist]: https://perfectionist.dev
+[plugin-playwright]: https://github.com/mskelton/eslint-plugin-playwright
+[plugin-promise]: https://github.com/eslint-community/eslint-plugin-promise
+[plugin-react]: https://eslint-react.xyz
+[plugin-react-hooks]: https://react.dev/reference/eslint-plugin-react-hooks
+[plugin-storybook]: https://storybook.js.org/docs/configure/integration/eslint-plugin
+[plugin-stylistic]: https://eslint.style
+[plugin-tailwind]: https://github.com/schoero/eslint-plugin-better-tailwindcss
+[plugin-ts]: https://typescript-eslint.io
+[plugin-unicorn]: https://github.com/sindresorhus/eslint-plugin-unicorn
+[plugin-vitest]: https://github.com/vitest-dev/eslint-plugin-vitest
+[plugin-vue]: https://eslint.vuejs.org
+[plugin-vue-a11y]: https://vue-a11y.github.io/eslint-plugin-vuejs-accessibility
+[plugin-zod]: https://github.com/marcalexiei/eslint-zod
+
+<!-- References -->
+[antfu]: https://github.com/antfu
+[contributing]: ./.github/CONTRIBUTING.md
+[eslint]: https://eslint.org
+[online-preview]: https://eslintconfig.netlify.app
+[eslint-config-ts-setup]: https://eslint.org/docs/latest/use/configure/configuration-files#typescript-configuration-files
+[eslint-nuxt]: https://eslint.nuxt.com
+[local-pkg]: https://github.com/antfu-collective/local-pkg
+[prettier-shared-config]: https://prettier.io/docs/sharing-configurations
+[releases]: https://github.com/ShayanTheNerd/eslint-config/releases
+[semver]: https://semver.org
+[ShayanTheNerd]: https://github.com/ShayanTheNerd