{"id":10539,"library":"babel-plugin-react-compiler","title":"Babel Plugin for React Compiler","description":"The `babel-plugin-react-compiler` package, currently at version `1.0.0`, is a core component for integrating the React Compiler (codenamed \"Forget\") into JavaScript projects. Its primary function is to automatically memoize React components and hook calls at compile-time, aiming to eliminate unnecessary re-renders and significantly improve application performance without requiring manual `useMemo` or `useCallback` optimizations. This plugin is developed as part of the broader React ecosystem by Facebook/Meta, closely tied to the React core libraries, particularly with the release of React 19. While the plugin itself is at an initial `1.0.0` stable release, the underlying React Compiler is an actively evolving project, receiving continuous updates and refinements alongside major React versions. Its release cadence is therefore coupled with the React framework's development cycle, which often sees patch releases for bug fixes and performance improvements, with feature updates aligning with major React releases. This compiler is a key differentiator for React, promising \"zero-cost\" memoization for developers.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/react","tags":["javascript","typescript"],"install":[{"cmd":"npm install babel-plugin-react-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-react-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-react-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Babel to run the plugin during the compilation process.","package":"@babel/core","optional":false},{"reason":"The compiler is designed to optimize React applications and is tightly coupled with React's internal mechanisms, particularly React 19, though it supports React 17 and 18 with additional configuration.","package":"react","optional":false},{"reason":"This runtime package provides the necessary hooks for the compiler's memoization strategy, especially when supporting React versions below 19.","package":"react-compiler-runtime","optional":true}],"imports":[{"note":"Babel plugins are consumed as string names in configuration files, not imported directly into application code. This basic setup enables the compiler with default options.","wrong":"import { ReactCompilerPlugin } from 'babel-plugin-react-compiler'","symbol":"Babel Plugin Configuration (Basic)","correct":"plugins: ['babel-plugin-react-compiler']"},{"note":"When passing options to a Babel plugin, the plugin name and its options object must be enclosed within an additional array.","wrong":"plugins: ['babel-plugin-react-compiler', { /* options */ }]","symbol":"Babel Plugin Configuration (With Options)","correct":"plugins: [['babel-plugin-react-compiler', { /* options */ }]]"},{"note":"For Vite projects using `@vitejs/plugin-react`, the `babel-plugin-react-compiler` needs to be configured under the `babel.plugins` option of `vite-plugin-react`. It must be the first plugin in the Babel pipeline.","wrong":"plugins: ['babel-plugin-react-compiler'] // directly in defineConfig plugins array for Vite","symbol":"Babel Plugin in Vite (using @vitejs/plugin-react)","correct":"import { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [\n    react({\n      babel: {\n        plugins: ['babel-plugin-react-compiler'], // must run first!\n      },\n    }),\n  ],\n});"}],"quickstart":{"code":"/* babel.config.js */\nmodule.exports = {\n  presets: ['@babel/preset-env', '@babel/preset-react'],\n  plugins: [\n    // The React Compiler plugin must run first in the Babel plugin pipeline.\n    'babel-plugin-react-compiler',\n    // ... other Babel plugins (e.g., for TypeScript, JSX transform)\n  ],\n};\n\n/* src/App.js */\nimport { useState } from 'react';\n\nfunction Header() {\n  console.log('Header re-rendered');\n  return <h1>React Compiler Demo</h1>;\n}\n\nexport default function App() {\n  const [count, setCount] = useState(0);\n\n  // With React Compiler, Header should not re-render when count changes\n  // unless its props change or it's forced to.\n  return (\n    <div>\n      <Header />\n      <p>Count: {count}</p>\n      <button onClick={() => setCount(c => c + 1)}>\n        Increment\n      </button>\n      <ExpensiveCalculation value={count} />\n    </div>\n  );\n}\n\nfunction ExpensiveCalculation({ value }) {\n  // Simulate an expensive computation that the compiler might memoize\n  let result = 0;\n  for (let i = 0; i < 1_000_000; i++) {\n    result += Math.sqrt(i) * value;\n  }\n  console.log('ExpensiveCalculation re-rendered with value:', value);\n  return <p>Expensive Result: {result.toFixed(2)}</p>;\n}","lang":"javascript","description":"This quickstart demonstrates how to configure the `babel-plugin-react-compiler` in a `babel.config.js` file and shows a basic React component structure where the compiler can automatically optimize re-renders for a `Header` and an `ExpensiveCalculation` component when only unrelated state (`count`) updates in the parent `App` component."},"warnings":[{"fix":"For new code, rely on the compiler for memoization. For existing code, gradually remove manual memoization after careful testing to ensure no regressions. The compiler acts as an escape hatch for specific, advanced scenarios.","message":"The React Compiler is designed to largely replace manual memoization (`useMemo`, `useCallback`, `React.memo`). While it can coexist with existing manual memoization, completely removing existing manual memoization should be done cautiously, as it can subtly change compilation output and behavior.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure 'babel-plugin-react-compiler' is the very first entry in the `plugins` array of your `babel.config.js` or equivalent Babel configuration.","message":"The `babel-plugin-react-compiler` must be the first plugin in your Babel plugin pipeline. If other transformation plugins run before it, the compiler may not receive the original source information needed for proper analysis and optimization, leading to unexpected behavior or skipped optimizations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For optimal compatibility and features, consider upgrading your project to React 19. If using React 17 or 18, install `react-compiler-runtime` and configure the compiler's `target` option to match your React version.","message":"While the React Compiler supports React versions 17 and 18, it is explicitly designed to work best with React 19. Using it with older React versions might require additional configuration, specifically installing `react-compiler-runtime` as a direct dependency and configuring a `target` option.","severity":"gotcha","affected_versions":"<19.0.0 for React"},{"fix":"Install and configure `eslint-plugin-react-compiler` to proactively identify and fix code patterns that violate the Rules of React, ensuring maximum compiler optimization.","message":"The compiler introduces stricter adherence to the 'Rules of React'. It includes an ESLint rule (`eslint-plugin-react-compiler`) that identifies code patterns preventing optimization, such as mutating props or reading refs during render. Violations will cause the compiler to skip optimization for affected components.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Monitor your build times. Ensure your Babel setup utilizes caching effectively. The performance gains at runtime are expected to outweigh the build time increase for most applications.","message":"Initial integration of the compiler might modestly increase build times due to the new analysis and optimization step. While optimized runtime performance is the goal, the build process adds a new layer.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the package using `npm install --save-dev babel-plugin-react-compiler` or `yarn add --dev babel-plugin-react-compiler`. Verify the plugin name in your `babel.config.js` or `.babelrc`.","cause":"The package `babel-plugin-react-compiler` is either not installed or its name is misspelled in the Babel configuration.","error":"Error: Plugin 'babel-plugin-react-compiler' not found."},{"fix":"Correct the Babel configuration to wrap the plugin name and options in an inner array: `plugins: [['babel-plugin-react-compiler', { /* options */ }]]`.","cause":"When providing options to a Babel plugin, the plugin name and its options object must be enclosed within an inner array, e.g., `[['plugin-name', { options }]]`.","error":"TypeError: 'plugins' must be an array of arrays or strings."},{"fix":"Review components for redundant manual memoization and consider removing them. Utilize `eslint-plugin-react-compiler` to identify and fix code patterns preventing optimal compiler functioning.","cause":"This can occur due to subtle conflicts with existing manual `useMemo` / `useCallback` or violations of the Rules of React that the compiler now exposes.","error":"Unexpected component re-renders or incorrect memoization behavior after enabling the compiler."},{"fix":"Install `react-compiler-runtime` as a direct dependency: `npm install react-compiler-runtime` or `yarn add react-compiler-runtime`. Ensure your bundler includes it in the output.","cause":"This error occurs when the `react-compiler-runtime` package is required but not installed, typically when targeting React versions older than 19 or within a library.","error":"Cannot find module 'react-compiler-runtime'"}],"ecosystem":"npm"}