@caspeco/eslint-config-react

Caspeco ESLint configuration for React + TypeScript projects.

Installation

npm install --save-dev @caspeco/eslint-config-react

Migrating from v4.x

If you're upgrading from @caspeco/eslint-config v4.x, use the automated migration script:

# Preview changes
npx caspeco-react-migrate-v5 src/ --dry-run

# Apply changes
npx caspeco-react-migrate-v5 src/

This updates the plugin namespace from caspeco/ to caspeco-react/. See the Migration Guide for details.

Usage

Create an eslint.config.js file in your project root:

import config from "@caspeco/eslint-config-react";

export default [{ ignores: ["dist/**/*", "build/**/*"] }, ...config];

React Compiler (opt-in)

If your project has adopted the React Compiler, use the /compiler entry point instead. It is a drop-in replacement that enables the full eslint-plugin-react-hooks recommended ruleset, including the React Compiler rules (react-hooks/purity, react-hooks/static-components, react-hooks/use-memo, react-hooks/immutability, react-hooks/set-state-in-render, and more):

import config from "@caspeco/eslint-config-react/compiler";

export default [{ ignores: ["dist/**/*", "build/**/*"] }, ...config];

The default config (@caspeco/eslint-config-react) intentionally enables only react-hooks/rules-of-hooks and react-hooks/exhaustive-deps, so teams that have not yet adopted the React Compiler are not flooded with compiler-specific warnings.

What's Included

This configuration includes everything from our TypeScript config plus React-specific rules:

Base TypeScript Configuration

• TypeScript ESLint - recommended-type-checked config
• No Barrel Files - Prevents barrel file usage
• File Naming Conventions - Enforces kebab-case for files and folders
• Prettier Integration - Compatible with Prettier formatting

React-Specific Configuration

• React Plugin - Core React linting rules
• React Hooks - Enforces rules of hooks
• React Refresh - Fast Refresh support for Vite/development
• Caspeco Plugin - Custom rules for Caspeco projects (Chakra UI import restrictions)

Peer Dependencies

This package requires the following peer dependencies (automatically installed by npm 7+):

• eslint (9 or 10)
• eslint-plugin-react-hooks
• eslint-plugin-react-refresh
• globals

See package.json for specific version requirements.

Note: Additional TypeScript-related peer dependencies are inherited from @caspeco/eslint-config-ts (installed automatically as a regular dependency).

eslint-plugin-react is a regular dependency, not a peer. It has no release that supports ESLint 10 yet, so this package patches it with fixupRule from @eslint/compat.

ESLint 10

• Remove eslint-plugin-react from your own package.json, or npm fails with ERESOLVE.
• npm prints npm warn ERESOLVE overriding peer dependency for eslint-plugin-react. The install succeeds and linting works.
• Installs with strict peer dependencies (e.g. pnpm strict-peer-dependencies) fail until eslint-plugin-react supports ESLint 10.
• Use @eslint/js 10 with ESLint 10. Its recommended adds no-useless-assignment, no-unassigned-vars and preserve-caught-error.
• On ESLint 9, keep @eslint/js on ^9. A fresh install without a lockfile otherwise picks @eslint/js 10.

Plugins

eslint-plugin-react

eslint-plugin-react

Core React linting rules with the following customizations:

• react-in-jsx-scope: off (not needed in modern React)
• prop-types: off (using TypeScript instead)
• display-name: off

eslint-plugin-react-hooks

eslint-plugin-react-hooks

Enforces:

• Rules of Hooks (error)
• Exhaustive dependencies (warning)

eslint-plugin-react-refresh

eslint-plugin-react-refresh

Ensures components are compatible with Fast Refresh in development.

caspeco-react-plugin

Custom React-specific plugin with Caspeco rules:

• Discourages direct imports from @chakra-ui/react (use themed components instead)

Relationship with @caspeco/eslint-config-ts

This package depends on and extends @caspeco/eslint-config-ts, which is automatically installed as a dependency. This ensures React projects always use the same TypeScript rules without drift. If you're building a React project, use this package. For vanilla TypeScript projects, use @caspeco/eslint-config-ts.

License

MIT