@bonesofspring/eslint-react

ESLint flat config for React + TypeScript projects.

Note: This package is primarily intended for personal use by Revy Ross. It is published for convenience but may not suit all projects.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Editor Setup
• TypeScript
• Config Exports
• Plugins and Rules
• Maintenance
• License

Features

• Import order — Sorted imports with import-x/order (fixable)
• Unused imports — Auto-removal with unused-imports/no-unused-imports (fixable)
• React & TypeScript — Airbnb-style rules, React Hooks, JSX a11y
• Code quality — SonarJS, Unicorn, consistent type imports
• Formatting — Prettier integration, @stylistic rules
• Optional — Next.js, Jest, Testing Library, Markdown, Security, Promise, RegExp, JSDoc

Requirements

• ESLint ^10.0.0
• Prettier >= 3.0.0
• TypeScript >= 5.0.0 (for type-aware rules and import resolver)
• Node.js >= 22.12.0
• Optional: eslint-import-resolver-typescript for TypeScript path aliases in import-x

Installation

yarn add -D @bonesofspring/eslint-react eslint prettier typescript eslint-import-resolver-typescript

Quick Start

// eslint.config.js
import config from '@bonesofspring/eslint-react'

export default config

Configuration

Full config (default)

Includes core React + TypeScript rules, scoped Jest/Testing Library rules for test files, and Markdown linting. Does not include Next.js or optional plugins (security, promise, regexp, jsdoc) — add them explicitly when needed.

// eslint.config.js
import config from '@bonesofspring/eslint-react'

export default config

Next.js project

// eslint.config.js
import config from '@bonesofspring/eslint-react'
import next from '@bonesofspring/eslint-react/next'

export default [...config, ...next]

Modular configs

Import only the configs you need:

// eslint.config.js
import core from '@bonesofspring/eslint-react/core'
import jest from '@bonesofspring/eslint-react/jest'
import markdown from '@bonesofspring/eslint-react/markdown'

export default [...core, ...jest, ...markdown]

Or compose from individual layers:

import base from '@bonesofspring/eslint-react/base'
import typescript from '@bonesofspring/eslint-react/typescript'
import react from '@bonesofspring/eslint-react/react'
import imports from '@bonesofspring/eslint-react/imports'
import stylistic from '@bonesofspring/eslint-react/stylistic'
import prettier from '@bonesofspring/eslint-react/prettier'

export default [
  ...base,
  ...typescript,
  ...react,
  ...imports,
  ...stylistic,
  ...prettier,
]

Optional plugins

import config from '@bonesofspring/eslint-react'
import security from '@bonesofspring/eslint-react/security'
import promise from '@bonesofspring/eslint-react/promise'

export default [...config, ...security, ...promise]

Editor Setup

Fix on save

VS Code / Cursor — add to settings.json:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

WebStorm — Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint → enable Run eslint --fix on save.

TypeScript

• Requires tsconfig.json (uses projectService: true).
• For import-x resolver with TypeScript paths, install eslint-import-resolver-typescript (optional peer dependency).

Config Exports

| Export | Description | |--------|-------------| | . | Default preset (core + scoped jest/testing-library + markdown) | | ./core | Base React + TS preset without test/markdown scoping | | ./base | Base ESLint + Airbnb rules | | ./typescript | TypeScript ESLint (recommended + strict) | | ./react | React, React Hooks, JSX a11y, You Might Not Need an Effect | | ./imports | import-x (order, no-cycle, etc.) | | ./stylistic | @stylistic (semi, quotes, etc.) | | ./unicorn | Unicorn (rules disabled by default) | | ./sonarjs | SonarJS (recommended) | | ./jest | Jest (flat/recommended, scoped to *.{test,spec}.*) | | ./next | Next.js (opt-in, scoped to source files) | | ./prettier | Prettier + unused-imports | | ./markdown | Markdown (lint .md files) | | ./testing-library | Testing Library (flat/react, scoped to test files) | | ./security | Security (recommended, opt-in) | | ./promise | Promise (flat/recommended, opt-in) | | ./regexp | RegExp (flat/recommended, opt-in) | | ./jsdoc | JSDoc (flat/recommended-typescript, opt-in) |

Plugins and Rules

Core

@eslint/js (base)

• Config: eslint.configs.recommended
• Custom rules: Airbnb-style base (best practices, errors, ES6, style, variables), plus:
  • arrow-body-style, no-duplicate-imports, max-lines (300), no-param-reassign, no-console, no-debugger, no-unused-vars (off)

typescript-eslint

• Config: recommended + strict
• Custom rules: consistent-type-imports, naming-convention (I/T/E prefixes), no-require-imports, etc.

eslint-plugin-react

• Rules: Airbnb-style React rules + overrides
• Key: jsx-curly-brace-presence, jsx-filename-extension (.tsx), jsx-sort-props, function-component-definition (arrow-function)

eslint-plugin-react-hooks

• Rules: rules-of-hooks (error), exhaustive-deps (warn)

eslint-plugin-react-you-might-not-need-an-effect

• Config: recommended (detects unnecessary useEffect)

eslint-plugin-jsx-a11y

• Rules: Airbnb-style accessibility rules

eslint-plugin-import-x

• Rules: first, no-cycle, newline-after-import, order (groups, newlines-between), no-extraneous-dependencies

@stylistic/eslint-plugin

• Rules: no-multiple-empty-lines, semi (never), padding-line-between-statements, quotes (single)

eslint-plugin-prettier

• Rules: prettier/prettier (singleQuote, no semi, trailingComma: all, printWidth: 100)

eslint-plugin-unused-imports

• Rules: no-unused-imports (error), no-unused-vars (warn, replaces @typescript-eslint/no-unused-vars)

Code quality

eslint-plugin-unicorn

• Config: flat/recommended with project-specific overrides
• Disabled: consistent-destructuring, filename-case, no-null, prevent-abbreviations, etc.
• Custom: no-empty-file (warn)

eslint-plugin-sonarjs

• Config: recommended
• Override: no-duplicate-string (off)

Framework-specific

@next/eslint-plugin-next

• Usage: opt-in via @bonesofspring/eslint-react/next
• Rules: Next.js best practices (no-html-link-for-pages, no-head-element, no-document-import-in-page, etc.)

Optional (opt-in subpath exports)

Import these subpaths when needed — each enables the plugin's recommended rules:

• eslint-plugin-jest — scoped to *.{test,spec}.* in default preset
• eslint-plugin-testing-library — scoped to test files in default preset
• eslint-plugin-security — @bonesofspring/eslint-react/security
• eslint-plugin-promise — @bonesofspring/eslint-react/promise
• eslint-plugin-regexp — @bonesofspring/eslint-react/regexp
• eslint-plugin-jsdoc — @bonesofspring/eslint-react/jsdoc

@eslint/markdown

• Files: **/*.md
• Rules: All markdown rules (fenced-code-language, heading-increment, no-empty-links, etc.)

Maintenance

After bumping ESLint or plugin dependencies, verify that all rule IDs in the config still exist:

yarn validate:rules

Runs scripts/validate-rules.mjs against effective flat config for JS, TypeScript/TSX, test, and Markdown fixtures (scripts/fixtures/), plus opt-in subpaths (./next, ./security, etc.). Also run yarn smoke:lint for runtime ESLint 10 compatibility checks.

License

MIT