@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.

Install

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

Basic Setup

Add this to eslint.config.ts:

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

export default defineConfig();

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

Customization

Disable Auto-Detection

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

export default defineConfig({ autoDetect: false });

Enable/Disable Rule Sets

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+):

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 are handled:

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 are being used:

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:

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

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 for overrides instead of writing your own:

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.

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 | ESLint directive comments | | @eslint-react/eslint-plugin | Modern React linting | | @eslint/js | Core ESLint rules | | @next/eslint-plugin-next | Next.js best practices | | @stylistic/eslint-plugin | Consistent formatting | | @tanstack/eslint-plugin-query | TanStack Query rules | | @vitest/eslint-plugin | Vitest support | | eslint-config-prettier | Disable formatting conflicts | | eslint-plugin-arrow-return-style-x | Arrow function return style | | eslint-plugin-astro | Astro framework support | | eslint-plugin-import-x | Import order and hygiene | | eslint-plugin-jest | Jest support | | eslint-plugin-jest-dom | DOM assertions for tests | | eslint-plugin-jsdoc | JSDoc comment rules | | eslint-plugin-jsx-a11y | Accessibility in JSX | | eslint-plugin-n | Node.js-specific rules | | eslint-plugin-perfectionist | Sorting and consistency | | eslint-plugin-playwright | Playwright testing support | | eslint-plugin-react-compiler | React Compiler rules | | eslint-plugin-react-hooks | Enforce React Hooks rules | | eslint-plugin-react-refresh | Safe Fast Refresh boundaries | | eslint-plugin-regexp | RegExp best practices | | eslint-plugin-storybook | Storybook support | | eslint-plugin-testing-library | Testing Library rules | | eslint-plugin-unicorn | Modern JavaScript best practices | | typescript-eslint | TypeScript linting and type safety |

Contributing

PRs and issues welcome.

Credits

Inspired by:

• @antfu/eslint-config by Anthony Fu
• @pvtnbr/eslint-config by Hiroki Osame