ESLint Plugin for React Compiler

19.1.0-rc.2 · active · verified Sun Apr 19

The `eslint-plugin-react-compiler` is an ESLint plugin designed to integrate with the experimental React Compiler (internally known as React Forget). Its primary function is to surface and display errors, warnings, and suggestions generated by the compiler directly within the developer's integrated development environment (IDE) or during continuous integration (CI) builds. Currently at version `19.1.0-rc.2`, it operates as a release candidate, indicating active development and potential for API instability. The plugin is a critical tool for developers experimenting with the React Compiler, providing immediate feedback on compilation issues and guiding them towards code patterns compatible with automatic memoization and optimization. Given its close tie to an experimental React feature, its release cadence is likely irregular and directly linked to the React Compiler's own development milestones, focusing on correctness and performance improvements. It differentiates itself by being the official mechanism to lint against compiler-specific issues, a function not covered by generic ESLint rules or other React-specific ESLint plugins.

Common errors

```
Error: Failed to load plugin 'react-compiler' declared in '.eslintrc.js': Cannot find module 'eslint-plugin-react-compiler'
```
cause The `eslint-plugin-react-compiler` package is not installed or not accessible in the current project environment.

fix Run `npm install eslint-plugin-react-compiler eslint --save-dev` or `yarn add eslint-plugin-react-compiler eslint --dev` to install the plugin and ESLint.
```
ESLint: Configuration for rule 'react-compiler/some-non-existent-rule' is invalid: Value 'error' is not allowed.
```
cause An ESLint rule specific to `eslint-plugin-react-compiler` has been configured incorrectly, either by referencing a non-existent rule or by using invalid options for an existing rule.

fix Double-check the rule name and its allowed options against the official `eslint-plugin-react-compiler` documentation. Ensure the rule actually exists and the severity/options are valid.
```
ESLint: 'react-compiler' was conflicted between ...
```
cause The `eslint-plugin-react-compiler` is being loaded multiple times from different locations or configurations, leading to conflicts.

fix Ensure the plugin is registered only once in your root ESLint configuration. If using layered configurations, verify that child configurations are not re-registering the plugin when it's already inherited from a parent config.

Warnings

breaking This plugin is currently at a Release Candidate (RC) stage (`19.1.0-rc.2`). This implies that its API, rules, and configuration options are subject to frequent changes without strict adherence to semantic versioning. Breaking changes are to be expected between minor and even patch versions.
Fix: Always consult the latest official React Compiler and plugin documentation before upgrading. Pin the exact version in `package.json` to prevent unexpected breaking changes during automated updates.
gotcha The functionality of this ESLint plugin is directly tied to the experimental React Compiler. Incorrect or incomplete setup of the React Compiler itself in your project may lead to the ESLint plugin not reporting errors accurately or at all.
Fix: Ensure your project is correctly configured to use the experimental React Compiler. Refer to the official React documentation for the React Compiler setup instructions, which may involve specific Babel or bundler configurations.
gotcha Rule names and configurations within `eslint-plugin-react-compiler` are still in active development and may change or be removed as the React Compiler evolves. Relying on specific rule names or options without checking the latest documentation can lead to invalid ESLint configurations.
Fix: Regularly review the plugin's documentation and release notes. Prioritize using the `recommended` configuration (`'plugin:react-compiler/recommended'`) to automatically keep up with best practices and rule changes, rather than hand-picking individual rules.

Install

npm install eslint-plugin-react-compiler npm
yarn add eslint-plugin-react-compiler yarn
pnpm add eslint-plugin-react-compiler pnpm

Imports

Plugin registration
wrong:
```
const ReactCompiler = require('eslint-plugin-react-compiler'); // Incorrect usage in .eslintrc.js
```
correct:
```
plugins: ['react-compiler']
```
ESLint plugins are registered as strings within the `plugins` array in your ESLint configuration file (e.g., `.eslintrc.js`), not imported as modules into application code.
Recommended configuration
wrong:
```
extends: ['react-compiler'] // Missing 'plugin:' prefix
```
correct:
```
extends: ['plugin:react-compiler/recommended']
```
To utilize the plugin's predefined recommended ruleset, use the `plugin:` prefix followed by the plugin name and `/recommended` in the `extends` array.
Individual rule configuration
wrong:
```
rules: { 'no-expression-as-prop': 'error' } // Missing plugin name prefix
```
correct:
```
rules: { 'react-compiler/no-expression-as-prop': 'error' }
```
When configuring individual rules from a plugin, you must prefix the rule name with the plugin identifier (e.g., `react-compiler/`) to ensure it's correctly applied.

Quickstart

This configuration snippet demonstrates how to set up ESLint to utilize `eslint-plugin-react-compiler` within a React project. It includes the plugin in the `plugins` array and extends its recommended ruleset, allowing ESLint to detect and report errors, warnings, and suggestions generated by the experimental React Compiler directly in your development environment.

module.exports = {
  root: true,
  env: {
    browser: true,
    es2020: true,
    node: true
  },
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    ecmaFeatures: {
      jsx: true
    }
  },
  settings: {
    react: {
      version: 'detect' // Automatically detect React version
    }
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react/jsx-runtime',
    'plugin:react-compiler/recommended' // Enable recommended rules from the compiler plugin
  ],
  plugins: [
    'react',
    'react-compiler' // Register the plugin
  ],
  rules: {
    // Example: Override or add specific rules if needed
    // 'react-compiler/no-render-prop-expression': 'warn'
  }
};

view raw JSON →