@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