ESLint Plugin for Extra React Hooks Rules

2.13.0 · active · verified Tue Apr 21

`eslint-plugin-react-hooks-extra` version `2.13.0` offers supplementary ESLint rules for React Hooks, designed to enforce advanced best practices and identify common pitfalls beyond the fundamental "Rules of Hooks" provided by the official `eslint-plugin-react-hooks`. This plugin is part of the larger `eslint-react` ecosystem, which actively maintains and develops its suite of linting tools, with recent beta releases for its `v5` major version (e.g., `v5.3.2-beta.0`). Although `eslint-plugin-react-hooks-extra` currently remains at `2.13.0`, it operates within an environment compatible with the `eslint-react` project's latest requirements. Its primary differentiator is providing "extra" or more opinionated rules that complement, rather than replace, existing React linting configurations, allowing developers to incrementally enhance their React Hooks linting strictness.

Common errors

```
ESLint couldn't find the plugin "react-hooks-extra".
```
cause The plugin package `eslint-plugin-react-hooks-extra` was not installed or is incorrectly referenced.

fix Install the package: `npm install --save-dev eslint-plugin-react-hooks-extra` or `yarn add --dev eslint-plugin-react-hooks-extra`. Ensure the plugin is listed correctly in your ESLint configuration (`plugins` array or imported in `eslint.config.js`).
```
Configuration for rule "react-hooks-extra/rules-of-hooks" is invalid. Rule "rules-of-hooks" was not found.
```
cause Attempting to use a rule from `eslint-plugin-react-hooks` (the official plugin) under the `react-hooks-extra` plugin namespace.

fix Rules like `rules-of-hooks` and `exhaustive-deps` belong to the official `eslint-plugin-react-hooks`. Use the correct namespace: `react-hooks/rules-of-hooks: "error"`.
```
Error: You must be running a supported version of Node.js. Currently supported versions are >=20.19.0.
```
cause The Node.js version in your environment does not meet the minimum requirements for the `eslint-react` ecosystem.

fix Upgrade your Node.js installation to version `20.19.0` or newer. Use `nvm` or your preferred Node.js version manager.

Warnings

breaking The broader `eslint-react` project, which `eslint-plugin-react-hooks-extra` is part of, introduced significant breaking changes in its `v5.0.0-beta.0` and `v5.0.2-beta.0` releases for its core (`@eslint-react/core`) and toolkit (`@eslint-react/kit`) APIs. These changes include simplified `RuleToolkit.is` API, renamed internal checkers (e.g., `initializedFromReact` to `APIFromReact`), and a large-scale refactor of core package structure and API names (e.g., `isReactAPI` to `isAPI`). Projects upgrading the entire `eslint-react` suite to `v5.x` will need to adapt to these internal API changes if they have custom rules or advanced configurations depending on `eslint-react`'s internals.
Fix: Refer to the `eslint-react` project's official migration guide for `v5.x` on GitHub (github.com/Rel1cx/eslint-react/releases) to update custom rules or configurations that rely on the affected internal APIs.
gotcha `eslint-plugin-react-hooks-extra` is distinct from the official `eslint-plugin-react-hooks` (`@eslint-react/eslint-plugin-react-hooks`). The 'extra' plugin provides additional, often more opinionated, rules for Hooks and is intended to supplement, not replace, the official plugin which enforces the fundamental "Rules of Hooks". Ensure both are configured if you desire comprehensive linting.
Fix: Include both `eslint-plugin-react-hooks` (or its recommended config) and `eslint-plugin-react-hooks-extra` in your ESLint configuration to benefit from both sets of rules. For example, in Flat Config: `extends: [reactHooks.configs.flat.recommended, hooksExtra.configs.recommended]`.
gotcha Full functionality and type-aware rules of `eslint-plugin-react-hooks-extra` often require TypeScript and `typescript-eslint` to be correctly configured. Ignoring TypeScript setup may lead to some rules not working as expected or providing less accurate results.
Fix: Ensure `typescript` is installed as a peer dependency and `typescript-eslint` is configured in your ESLint setup, particularly extending `tseslint.configs.recommended` and providing correct `parserOptions` for type checking.

Install

npm install eslint-plugin-react-hooks-extra npm
yarn add eslint-plugin-react-hooks-extra yarn
pnpm add eslint-plugin-react-hooks-extra pnpm

Imports

ESLint Flat Config Plugin Object
wrong:
```
const hooksExtra = require("eslint-plugin-react-hooks-extra");
```
correct:
```
import hooksExtra from "eslint-plugin-react-hooks-extra";
```
For ESLint Flat Config (`eslint.config.js`), the plugin is imported as an ES module. CommonJS `require` is generally not used for Flat Config.
Legacy Config Plugin Name
wrong:
```
// .eslintrc.js
'plugins': ['@eslint-react/hooks-extra']
```
correct:
```
// .eslintrc.js or package.json
'plugins': ['react-hooks-extra']
```
In legacy ESLint configurations (`.eslintrc.*`), the plugin is referenced by its short name `react-hooks-extra`.

Legacy Recommended Config

wrong:

// .eslintrc.js
'extends': ['plugin:@eslint-react/hooks-extra/recommended']

correct:

// .eslintrc.js or package.json
'extends': ['plugin:react-hooks-extra/recommended']

To extend the recommended configuration in legacy ESLint setups, use `plugin:react-hooks-extra/recommended`.

Quickstart

This quickstart demonstrates setting up `eslint-plugin-react-hooks-extra` using ESLint Flat Config (`eslint.config.js`) with TypeScript, extending recommended configurations and showing an example of individual rule customization.

import js from "@eslint/js";
import hooksExtra from "eslint-plugin-react-hooks-extra";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

export default defineConfig( {
  files: ["**/*.{ts,tsx}"],
  extends: [
    js.configs.recommended,
    tseslint.configs.recommended,
    // Add configs from eslint-plugin-react-hooks-extra
    hooksExtra.configs.recommended,
  ],
  rules: {
    // Example: Override or add individual rules
    "react-hooks-extra/no-direct-set-state-in-use-effect": "warn",
    "react-hooks-extra/no-redundant-useState": "error" 
  },
});

view raw JSON →