eslint-plugin-react-hooks-configurable

Fork of eslint-plugin-react-hooks that allow a bit more configuration than the original plugin.

The configurable part was originally made by Stephen Sugden (@grncdr) (you can see its package on NPM).
The difference with this version is that this one uses the same numbering as the official version for an easy replacement (in one way or the other), the source are publicly accessible, it contains some documentation (see below :)) and, at the time of writing anyway, it is synchronized with the original version and solves compatibility issues with ESLint.

Rules

Rule react-hooks-configurable/exhaustive-deps

The rule works the same way as the original one, you just have more options to best configure it, see below.

additionalHooks option

This option allow to validate dependencies of your custom hooks.

import reactHooksConfigurable from 'eslint-plugin-react-hooks-configurable';

export default [{
  plugins: {
    'react-hooks-configurable': reactHooksConfigurable,
  },
  rules: {
    // ...
    'react-hooks-configurable/exhaustive-deps': ['warn', {
      additionalHooks: '(useMyCustomHook|useMyOtherCustomHook)',
    }],
  },
}];

The original rule already allowed you to do this, but with this plugin's rule, you have in addition the possibility to specify at which position the function that uses the dependencies is located in your custom hook.
(the original rule ALWAYS assumes that the function is placed first in the arguments)

Suppose you have the following custom hook:

const useMyImperativeHandle = (ref, fn, deps) => {
    // ...
};

export default useMyImperativeHandle;

In this case, you will configure the rule as follows:

// ... In configuration of the `react-hooks-configurable/exhaustive-deps` rule:
{
  additionalHooks: {
    '(useMyCustomHook|useMyOtherCustomHook)': 0,
    'useMyImperativeHandle': 1,
  }
}

(original idea of @squirly, see here https://github.com/facebook/react/issues/16873#issuecomment-610702001)

Note: Unlike the original rule, the patterns of this fork (for both additionalHooks and additionalStableHooks) are matched against the full Hook name. For example useFoo matches a Hook named exactly useFoo, but not useFooBar; use a pattern such as useFoo.* if you want prefix matching.

additionalStableHooks option

This option allow you to specify additional stable hooks in addition to those provided by react (useState, useRef, etc.).

import reactHooksConfigurable from 'eslint-plugin-react-hooks-configurable';

export default [{
  plugins: {
    'react-hooks-configurable': reactHooksConfigurable,
  },
  rules: {
    // ...
    'react-hooks-configurable/exhaustive-deps': ['warn', {
      additionalStableHooks: {
        'use.+Ref': true,
        'useMyCustomUseState': [false, true],
        'useMyQuery': {
          'data': false,
          'refetch': true,
        },
      },
    }],
  },
}];

With the original rule, only some core hooks are known to return stable elements:

• The return value from useRef.
• The setter from useState.
• The dispatcher function from useReducer.
• The startTransition function from useTransition.

The additionalStableHooks option of this plugin allows you to define some of your custom hooks as stable, fully or partially.
(By "partially" i mean that some of the elements returned by your hook are stable but not some others, as for useState, useReducer above)

Note that you can use a regex as a custom hook name if you use a naming convention for some of your stables hooks. For example, if you always return a stable ref from your components named use___Ref (useFunctionRef, useUpdatedRef, etc.), you could define:

// ... In configuration of the `react-hooks-configurable/exhaustive-deps` rule:
{
  additionalStableHooks: { "use.+Ref": true },
}

Partially stable custom hooks

If at least part of what your custom hook returns is not stable, you should avoid marking it as completely stable (e.g. { "useMyHook": true }) Instead of doing that, you can specify which returns are stable and which are not.

• If your custom hook returns a tuple (like useState), instead of passing true in front of your hook name in the rule configuration, pass an array with, for each element of the tuple returned by your hook, true or false depending on whether it is stable or not.

  Example with a custom hook named useMyCustomUseState which have the same return type as useState:

  // ... In configuration of the `react-hooks-configurable/exhaustive-deps` rule:
  {
    additionalStableHooks: { 
      'useMyCustomUseState': [false, true],
    },
  }

• If your custom hook returns an object of which only a few keys are stable, instead of passing true in front of your hook name in the rule configuration, pass an object with, for each key of your hook's return object, true or false depending on whether it is stable or not.

  Example:
  Supposes we have a useQuery hook that return an object with:

  • a data key containing the data from an external source.
  • a refetch key which will contain a function allowing you to refetch the data whenever you want.
    => You have made this function stable (like the dispatch function from useReducer).

  const useQuery = (endpoint) => {
    // ...
  
    return { data, refetch };
  };
  
  export default useQuery;

  In this case, you will configure the rule as follows:

  // ... In configuration of the `react-hooks-configurable/exhaustive-deps` rule:
  {
    additionalStableHooks: { 
      'useQuery': { 'data': false, 'refetch': true },
    },
  }

Other exhaustive-deps options

In addition to this fork's options, every option of the original exhaustive-deps rule is supported as-is.

• requireExplicitEffectDeps (boolean, default false)
  Reports effect Hooks called without a dependency array.
• experimental_autoDependenciesHooks (string[], default [])
  List of Hook names whose dependencies are inferred automatically, so a null / missing dependency array is not reported for them.
• enableDangerousAutofixThisMayCauseInfiniteLoops (boolean, default false)
  Turns the suggested fix into an automatically applied fix.

additionalEffectHooks shared setting

The shared ESLint setting introduced upstream is also honored:
When no rule-level additionalHooks is provided, the rule falls back to it:

export default [{
  settings: {
    'react-hooks': {
      additionalEffectHooks: '(useMyCustomEffect)',
    },
  },
  // ...
}];

Other rules

Every rule of the original plugin is re-exported under the react-hooks-configurable namespace, and the recommended / recommended-latest configs mirror the ones shipped by the original plugin.
These rules behave exactly like their upstream counterparts.

The table below lists the publicly documented rules. In the "Recommended" column, ✅ means the rule is enabled in the recommended config, and 🧪 means it is enabled only in recommended-latest.

| Rule | Recommended | Description | |---|:---:|---| | react-hooks-configurable/rules-of-hooks | ✅ 🧪 | Validates that components and hooks follow the Rules of Hooks | | react-hooks-configurable/config | ✅ 🧪 | Validates the compiler configuration options | | react-hooks-configurable/error-boundaries | ✅ 🧪 | Validates usage of Error Boundaries instead of try/catch for child errors | | react-hooks-configurable/gating | ✅ 🧪 | Validates configuration of gating mode | | react-hooks-configurable/globals | ✅ 🧪 | Validates against assignment/mutation of globals during render | | react-hooks-configurable/immutability | ✅ 🧪 | Validates against mutating props, state, and other immutable values | | react-hooks-configurable/incompatible-library | ✅ 🧪 | Validates against usage of libraries which are incompatible with memoization | | react-hooks-configurable/preserve-manual-memoization | ✅ 🧪 | Validates that existing manual memoization is preserved by the compiler | | react-hooks-configurable/purity | ✅ 🧪 | Validates that components/hooks are pure by checking known-impure functions | | react-hooks-configurable/refs | ✅ 🧪 | Validates correct usage of refs, not reading/writing during render | | react-hooks-configurable/set-state-in-effect | ✅ 🧪 | Validates against calling setState synchronously in an effect | | react-hooks-configurable/set-state-in-render | ✅ 🧪 | Validates against setting state during render | | react-hooks-configurable/static-components | ✅ 🧪 | Validates that components are static, not recreated every render | | react-hooks-configurable/unsupported-syntax | ✅ 🧪 | Validates against syntax that React Compiler does not support | | react-hooks-configurable/use-memo | ✅ 🧪 | Validates usage of the useMemo hook without a return value | | react-hooks-configurable/void-use-memo | 🧪 | Validates that useMemos always return a value and that their result is used |