@jimmy.codes/eslint-config/README.md

A simple, modern ESLint config that covers most use cases.

# @jimmy.codes/eslint-config

![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/jimmy-guzman/eslint-config/cd.yml?style=flat-square&logo=github-actions)
[![version](https://img.shields.io/npm/v/@jimmy.codes/eslint-config.svg?logo=npm&style=flat-square)](https://www.npmjs.com/package/@jimmy.codes/eslint-config)
[![downloads](https://img.shields.io/npm/dm/@jimmy.codes/eslint-config.svg?logo=npm&style=flat-square)](http://www.npmtrends.com/@jimmy.codes/eslint-config)

> A simple, modern ESLint config that covers most use cases.

## Why Use This?

A strict but practical ESLint config that works out of the box, adapts to your stack, and enforces good patterns without getting in the way. It catches real bugs, reduces ambiguity, and keeps your codebase consistent.

- **Auto-detects your stack**: React, TypeScript, Astro, Next.js, Vitest, Jest, Testing Library, Playwright, Storybook, and TanStack Query.
- **Zero-config start**: Install it, extend it, done.
- **Prevents real issues**: Prioritizes rules that catch bugs and unsafe patterns.
- **Prevents confusion**: Flags ambiguous code, confusing promise usage, shadowed variables, and unused exports.
- **Enforces consistency**: Standardizes imports, naming, coding style, and testing conventions.
- **Flexible**: Easily customize or disable any part of the config.
- **Favors recommended**: Where possible, builds on top of official recommended rulesets from plugins.
- **Maintained**: Regularly updated to keep up with best practices, new tools, language features and new rules

---

## Installation & Usage

> [!NOTE]  
> Works best with [@jimmy.codes/prettier-config](https://github.com/jimmy-guzman/prettier-config).

### Install

```sh
pnpm add -D @jimmy.codes/eslint-config
```

### Basic Setup

Add this to `eslint.config.ts`:

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig();
```

It'll auto-configure based on your installed dependencies.

---

## Customization

### Disable Auto-Detection

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({ autoDetect: false });
```

### Enable/Disable Rule Sets

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  astro: false,
  jest: false,
  nextjs: false,
  playwright: false,
  react: false,
  storybook: false,
  tanstackQuery: false,
  testingLibrary: false,
  typescript: false,
  vitest: false,
});
```

### TypeScript Configuration

TypeScript also supports some configuration options. If options are provided then TypeScript support is enabled.

#### Configure Erasable Syntax Only

Enable rules scoped to [TypeScript's new erasable syntax only mode (TypeScript 5.8+)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-8.html#the---erasablesyntaxonly-option):

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  typescript: {
    erasableSyntaxOnly: true,
  },
});
```

### Vitest Configuration

Vitest also supports some configuration options. If options are provided then Vitest support is enabled.

#### Configure Vitest Globals

Control how [Vitest globals configuration](https://vitest.dev/config/globals.html) are handled:

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  vitest: {
    globals: "explicit",
  },
});
```

Options:

- `'explicit'`: Require explicit imports from `'vitest'`
- `'implicit'`: Use implicit global APIs (vitest config `globals: true`)
- `'either'`: Allow both styles (default)

#### Configure Type Testing

Indicate whether [Vitest's type testing utilities](https://vitest.dev/guide/testing-types.html) are being used:

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  vitest: {
    typecheck: true,
  },
});
```

### Framework-Specific Rule Overrides

Many framework integrations support rule overrides, allowing you to fine-tune specific rules without affecting your entire config:

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  react: {
    overrides: {
      "react-x/no-array-index-key": "warn",
      "jsx-a11y/anchor-is-valid": "off",
    },
  },
  playwright: {
    overrides: {
      "playwright/no-focused-test": "error",
    },
  },
  jest: {
    overrides: {
      "jest/expect-expect": "off",
    },
  },
  testingLibrary: {
    overrides: {
      "testing-library/prefer-screen-queries": "warn",
    },
  },
  nextjs: {
    overrides: {
      "@next/next/no-img-element": "off",
    },
  },
  storybook: {
    overrides: {
      "storybook/no-uninstalled-addons": "warn",
    },
  },
  tanstackQuery: {
    overrides: {
      "@tanstack/query/exhaustive-deps": "error",
    },
  },
  astro: {
    overrides: {
      "astro/no-set-html-directive": "off",
    },
  },
  vitest: {
    overrides: {
      "vitest/no-conditional-expect": "warn",
    },
  },
  typescript: {
    overrides: {
      "@typescript-eslint/explicit-function-return-type": "error",
    },
  },
});
```

> [!TIP]
> Framework-specific overrides are scoped to only rules with the appropriate plugin prefix (e.g., `vitest/*` for Vitest, `react-x/*` for React). For broader rule overrides across specific file patterns, use the `overrides` array.

### Override Specific Rules

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  overrides: [
    {
      files: ["**/*.js"],
      rules: {
        "prefer-spread": "error",
      },
    },
    {
      files: ["**/*.ts"],
      rules: {
        "prefer-const": "error",
      },
    },
  ],
});
```

Or you can import [globs](src/globs.ts) for overrides instead of writing your own:

```ts
import { GLOB_JS, GLOB_TS } from "@jimmy.codes/eslint-config/globs";

export default defineConfig({
  overrides: [
    {
      files: [GLOB_JS],
      rules: {
        "prefer-spread": "error",
      },
    },
    {
      files: [GLOB_TS],
      rules: {
        "prefer-const": "error",
      },
    },
  ],
});
```

---

## Enable Git Ignore Support

Allows you to respect `.gitignore` files as ignore patterns.

```ts
import { defineConfig } from "@jimmy.codes/eslint-config";

export default defineConfig({
  gitignore: true,
});
```

---

## Plugins Used

This config includes the following plugins:

| Plugin                                                                                                                | Purpose                            |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [`@eslint-community/eslint-plugin-eslint-comments`](https://eslint-community.github.io/eslint-plugin-eslint-comments) | ESLint directive comments          |
| [`@eslint-react/eslint-plugin`](https://eslint-react.xyz/)                                                            | Modern React linting               |
| [`@eslint/js`](https://eslint.org/docs/latest/rules/)                                                                 | Core ESLint rules                  |
| [`@next/eslint-plugin-next`](https://nextjs.org/docs/basic-features/eslint)                                           | Next.js best practices             |
| [`@stylistic/eslint-plugin`](https://eslint.style/)                                                                   | Consistent formatting              |
| [`@tanstack/eslint-plugin-query`](https://tanstack.com/query/latest/docs/eslint/eslint-plugin-query)                  | TanStack Query rules               |
| [`@vitest/eslint-plugin`](https://github.com/vitest-dev/eslint-plugin-vitest)                                         | Vitest support                     |
| [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier)                                        | Disable formatting conflicts       |
| [`eslint-plugin-arrow-return-style-x`](https://github.com/christopher-buss/eslint-plugin-arrow-return-style-x)        | Arrow function return style        |
| [`eslint-plugin-astro`](https://ota-meshi.github.io/eslint-plugin-astro/)                                             | Astro framework support            |
| [`eslint-plugin-import-x`](https://github.com/un-ts/eslint-plugin-import-x)                                           | Import order and hygiene           |
| [`eslint-plugin-jest`](https://github.com/jest-community/eslint-plugin-jest)                                          | Jest support                       |
| [`eslint-plugin-jest-dom`](https://github.com/testing-library/eslint-plugin-jest-dom)                                 | DOM assertions for tests           |
| [`eslint-plugin-jsdoc`](https://github.com/gajus/eslint-plugin-jsdoc)                                                 | JSDoc comment rules                |
| [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)                                      | Accessibility in JSX               |
| [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n)                                              | Node.js-specific rules             |
| [`eslint-plugin-perfectionist`](https://perfectionist.dev)                                                            | Sorting and consistency            |
| [`eslint-plugin-playwright`](https://github.com/playwright-community/eslint-plugin-playwright)                        | Playwright testing support         |
| [`eslint-plugin-react-compiler`](https://www.npmjs.com/package/eslint-plugin-react-compiler)                          | React Compiler rules               |
| [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks)                                | Enforce React Hooks rules          |
| [`eslint-plugin-react-refresh`](https://github.com/ArnaudBarre/eslint-plugin-react-refresh)                           | Safe Fast Refresh boundaries       |
| [`eslint-plugin-regexp`](https://ota-meshi.github.io/eslint-plugin-regexp/)                                           | RegExp best practices              |
| [`eslint-plugin-storybook`](https://github.com/storybookjs/eslint-plugin-storybook)                                   | Storybook support                  |
| [`eslint-plugin-testing-library`](https://github.com/testing-library/eslint-plugin-testing-library)                   | Testing Library rules              |
| [`eslint-plugin-unicorn`](https://github.com/sindresorhus/eslint-plugin-unicorn)                                      | Modern JavaScript best practices   |
| [`typescript-eslint`](https://typescript-eslint.io/)                                                                  | TypeScript linting and type safety |

---

## Contributing

PRs and issues welcome.

---

## Credits

Inspired by:

- [@antfu/eslint-config](https://github.com/antfu/eslint-config) by [Anthony Fu](https://antfu.me)
- [@pvtnbr/eslint-config](https://github.com/privatenumber/eslint-config) by [Hiroki Osame](https://hirok.io)