7d29ecbeb2
NOTE: this is a merged version of @mofeiZ's original PR along with my edits per offline discussion. The description is updated to reflect the latest approach. The key problem we're trying to solve with this PR is to allow developers more control over the compiler's various validations. The idea is to have a number of rules targeting a specific category of issues, such as enforcing immutability of props/state/etc or disallowing access to refs during render. We don't want to have to run the compiler again for every single rule, though, so @mofeiZ added an LRU cache that caches the full compilation output of N most recent files. The first rule to run on a given file will cause it to get cached, and then subsequent rules can pull from the cache, with each rule filtering down to its specific category of errors. For the categories, I went through and assigned a category roughly 1:1 to existing validations, and then used my judgement on some places that felt distinct enough to warrant a separate error. Every error in the compiler now has to supply both a severity (for legacy reasons) and a category (for ESLint). Each category corresponds 1:1 to a ESLint rule definition, so that the set of rules is automatically populated based on the defined categories. Categories include a flag for whether they should be in the recommended set or not. Note that as with the original version of this PR, only eslint-plugin-react-compiler is changed. We still have to update the main lint rule. ## Test Plan * Created a sample project using ESLint v9 and verified that the plugin can be configured correctly and detects errors * Edited `fixtures/eslint-v9` and introduced errors, verified that the w latest config changes in that fixture it correctly detects the errors * In the sample project, confirmed that the LRU caching is correctly caching compiler output, ie compiling files just once. Co-authored-by: Mofei Zhang <feifei0@meta.com>
eslint-plugin-react-hooks
This ESLint plugin enforces the Rules of Hooks.
It is a part of the Hooks API for React.
Installation
Note: If you're using Create React App, please use react-scripts >= 3 instead of adding it directly.
Assuming you already have ESLint installed, run:
# npm
npm install eslint-plugin-react-hooks --save-dev
# yarn
yarn add eslint-plugin-react-hooks --dev
Flat Config (eslint.config.js|ts)
>= 6.0.0
For users of 6.0 and beyond, simply add the recommended config.
import * as reactHooks from 'eslint-plugin-react-hooks';
export default [
// ...
reactHooks.configs.recommended,
];
5.2.0
For users of 5.2.0 (the first version with flat config support), add the recommended-latest config.
import * as reactHooks from 'eslint-plugin-react-hooks';
export default [
// ...
reactHooks.configs['recommended-latest'],
];
Legacy Config (.eslintrc)
>= 5.2.0
If you are still using ESLint below 9.0.0, you can use recommended-legacy for accessing a legacy version of the recommended config.
{
"extends": [
// ...
"plugin:react-hooks/recommended-legacy"
]
}
< 5.2.0
If you're using a version earlier than 5.2.0, the legacy config was simply recommended.
{
"extends": [
// ...
"plugin:react-hooks/recommended"
]
}
Custom Configuration
If you want more fine-grained configuration, you can instead add a snippet like this to your ESLint configuration file:
Flat Config (eslint.config.js|ts)
import * as reactHooks from 'eslint-plugin-react-hooks';
export default [
{
files: ['**/*.{js,jsx}'],
plugins: { 'react-hooks': reactHooks },
// ...
rules: {
'react-hooks/rules-of-hooks': 'error',
'react-hooks/exhaustive-deps': 'warn',
}
},
];
Legacy Config (.eslintrc)
{
"plugins": [
// ...
"react-hooks"
],
"rules": {
// ...
"react-hooks/rules-of-hooks": "error",
"react-hooks/exhaustive-deps": "warn"
}
}
Advanced Configuration
exhaustive-deps can be configured to validate dependencies of custom Hooks with the additionalHooks option.
This option accepts a regex to match the names of custom Hooks that have dependencies.
{
rules: {
// ...
"react-hooks/exhaustive-deps": ["warn", {
additionalHooks: "(useMyCustomHook|useMyOtherCustomHook)"
}]
}
}
We suggest to use this option very sparingly, if at all. Generally saying, we recommend most custom Hooks to not use the dependencies argument, and instead provide a higher-level API that is more focused around a specific use case.
Valid and Invalid Examples
Please refer to the Rules of Hooks documentation to learn more about this rule.
License
MIT