Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Configuring the plugin
✓ plugins: ['react']
✗ plugins: [require('eslint-plugin-react')]
Registers the 'react' plugin with ESLint in the legacy .eslintrc* configuration.
Recommended Ruleset
✓ extends: ['plugin:react/recommended']
✗ extends: ['react/recommended']
Applies the recommended set of React-specific rules. Used in legacy .eslintrc* configs.
JSX Runtime Ruleset
✓ extends: ['plugin:react/jsx-runtime']
✗ Omitting this when using React 17+ new JSX transform.
Disables rules that become redundant or problematic with React 17's new JSX transform (e.g., 'react/react-in-jsx-scope').
React Version Detection
✓ settings: { react: { version: 'detect' } }
✗ settings: { react: { version: 'latest' } } (or omitting entirely)
Crucial for rules that depend on the installed React version. 'detect' automatically infers from package.json.
Flat Config (ESLint v9+)
✓ import reactPlugin from 'eslint-plugin-react';
export default [
reactPlugin.configs.flat.recommended,
reactPlugin.configs.flat['jsx-runtime'],
// ... other configs
];
✗ Using `extends: ['plugin:react/recommended']` in `eslint.config.js`.
For ESLint v9+, configurations are defined in `eslint.config.js` using a flat array of config objects. The plugin exposes its configurations under `reactPlugin.configs.flat`.
Demonstrates how to install `eslint-plugin-react` and configure it using both the legacy `.eslintrc.json` format (for ESLint < v9) and the new flat config `eslint.config.js` format (for ESLint v9+), including recommended presets and React version detection.
npm install --save-dev eslint eslint-plugin-react
// .eslintrc.json (Legacy ESLint config)
{
"env": {
"browser": true,
"es2021": true,
"node": true
},
"extends": [
"eslint:recommended",
"plugin:react/recommended",
"plugin:react/jsx-runtime" // For React 17+ new JSX transform
],
"parserOptions": {
"ecmaFeatures": {
"jsx": true
},
"ecmaVersion": "latest",
"sourceType": "module"
},
"plugins": [
"react"
],
"settings": {
"react": {
"version": "detect" // Automatically detects React version
}
},
"rules": {
// Add or override specific rules here, e.g.,
// "react/prop-types": "off"
}
}
// For ESLint v9+ (eslint.config.js)
// You would need to install @eslint/js for `js.configs.recommended`
// import globals from "globals";
// import js from "@eslint/js";
// import reactPlugin from "eslint-plugin-react";
// export default [
// js.configs.recommended,
// {
// files: ["**/*.{js,jsx,mjs,cjs,ts,tsx}"],
// ...reactPlugin.configs.flat.recommended,
// ...reactPlugin.configs.flat['jsx-runtime'], // For React 17+ new JSX transform
// languageOptions: {
// globals: {
// ...globals.browser,
// ...globals.node
// },
// parserOptions: {
// ecmaFeatures: {
// jsx: true
// },
// ecmaVersion: "latest",
// sourceType: "module"
// }
// },
// settings: {
// react: {
// version: "detect"
// }
// },
// rules: {
// // Add or override specific rules here
// }
// }
// ];
Debug
Known issues
breakingESLint v9 introduced a new flat configuration system (`eslint.config.js`). Legacy `.eslintrc*` files are deprecated and will not work without a compatibility layer. The plugin provides flat config presets, but migration is required for ESLint v9+ projects.fixMigrate your ESLint configuration to `eslint.config.js` using the new flat config format. Refer to `eslint-plugin-react`'s official documentation for updated flat config examples.
affects: eslint >= 9.0.0
gotchaWhen using React 17's new JSX transform (which automatically imports the `jsx` runtime), certain rules in `plugin:react/recommended` (like `react/react-in-jsx-scope`) become redundant and can cause errors if `plugin:react/jsx-runtime` is not extended.fixEnsure you add `"plugin:react/jsx-runtime"` to your `extends` array in your ESLint configuration.
affects: React >= 17.0.0
gotchaMany rules in `eslint-plugin-react` depend on knowing the exact React version installed in your project. If `settings.react.version` is not configured correctly or omitted, rules may produce incorrect warnings/errors or behave unexpectedly.fixAlways set `settings.react.version: "detect"` in your ESLint configuration for automatic detection from `package.json`. Alternatively, specify the exact version string (e.g., `"18.0"`) if autodetection is problematic or you need to override it.
affects: All versions
breaking`eslint-plugin-react` has strict peer dependency requirements for `eslint` itself (e.g., `^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9.7`). Installing incompatible `eslint` versions can lead to runtime errors where the plugin fails to load or function correctly.fixEnsure your `eslint` package version in `package.json` and `node_modules` matches the peer dependency range specified by `eslint-plugin-react`. Use `npm ls eslint` to check and adjust as needed.
affects: Any ESLint version outside the specified peer dependency range.
Errors
Common errors & fixes
Error: Failed to load plugin 'react' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-react'
The `eslint-plugin-react` npm package is not installed as a dependency in your project.
fixRun `npm install eslint-plugin-react --save-dev` or `yarn add eslint-plugin-react --dev` to install the plugin.
Parsing error: Cannot find module 'react' when using JSX (or similar 'React' must be in scope error).
ESLint's parser is not configured to understand JSX syntax, or the plugin is not properly recognizing the React environment. This often happens with React < 17 and `react/react-in-jsx-scope` rule, or when `jsx-runtime` is not configured for React 17+.
fixEnsure your `.eslintrc*` file includes `parserOptions.ecmaFeatures.jsx: true` and `settings.react.version: "detect"`. If using React 17+, add `"plugin:react/jsx-runtime"` to your `extends` array to disable the `react/react-in-jsx-scope` rule.
Warning: React version not specified in 'eslint-plugin-react settings'. See https://github.com/jsx-eslint/eslint-plugin-react/blob/master/README.md#configuration.
The `eslint-plugin-react` cannot determine which React version your project is using, which can lead to incorrect linting results for version-specific rules.
fixAdd `"settings": { "react": { "version": "detect" } }` to your `.eslintrc*` configuration file to enable automatic React version detection. Audit
Dependencies
eslintrequiredRequired peer dependency for ESLint functionality; the plugin registers its rules with ESLint.