React Compiler

Active contributors: josephsavona, mvitousek, mofeiZ, poteto, jbonta

Purpose

The compiler/ workspace is a separate Yarn 1 monorepo living inside the same git repo as the React runtime. It contains the React Compiler — a Babel/SWC-pluggable compiler that auto-memoizes React components and hooks, eliminating most hand-written useMemo, useCallback, and React.memo calls. It also doubles as a static analyzer for the Rules of React: it diagnoses things like setting state during render, calling hooks conditionally, accessing ref.current during render, and many subtler patterns.

Internally the project was called React Forget for years. The current public name is React Compiler. A few directories (compiler/packages/react-forgive/ — the VS Code extension) still carry the old name.

What ships

The compiler workspace publishes several npm packages:

Package	Path	Role
babel-plugin-react-compiler	compiler/packages/babel-plugin-react-compiler/	The compiler itself, as a Babel plugin.
eslint-plugin-react-compiler	compiler/packages/eslint-plugin-react-compiler/	A lint plugin that surfaces compiler diagnostics during normal development without needing a build.
react-compiler-runtime	compiler/packages/react-compiler-runtime/	A shim re-exporting react/compiler-runtime (c(N)) for users on older React versions.
react-compiler-healthcheck	compiler/packages/react-compiler-healthcheck/	A standalone CLI you point at a codebase to estimate compiler readiness.
react-forgive	compiler/packages/react-forgive/	A VS Code extension that surfaces compiler diagnostics inline.
react-mcp-server	compiler/packages/react-mcp-server/	An MCP server exposing compiler analysis to LLM agents.
make-read-only-util	compiler/packages/make-read-only-util/	Tiny dev helper for testing immutability assumptions.
snap	compiler/packages/snap/	The compiler's golden-file test runner (yarn snap).

The runtime side of the compiler — the c(N) runtime helper that compiled output calls — lives in packages/react/src/ReactCompilerRuntime.js and ships as part of react. The compiler emits calls like:

function MyComponent({ a, b }) {
  const $ = c(3);
  let t0;
  if ($[0] !== a) {
    t0 = a + 1;
    $[0] = a;
    $[1] = t0;
  } else {
    t0 = $[1];
  }
  // ...
}

The $ = c(3) call asks React for a per-render array of three slots; the body uses those slots as a memo cache.

Sub-pages

• architecture — the HIR, the pipeline shape, the env, how a Babel plugin invocation flows.
• passes — a map of every pass with its job and dependencies.

Where to start reading

• compiler/packages/babel-plugin-react-compiler/src/index.ts — the Babel plugin entry.
• compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts — the multi-pass pipeline orchestrator.
• compiler/packages/babel-plugin-react-compiler/src/HIR/HIR.ts — the central type definitions.
• compiler/packages/babel-plugin-react-compiler/src/HIR/Globals.ts — the table of known hook signatures.
• compiler/docs/DESIGN_GOALS.md — the team's public design philosophy.
• compiler/docs/DEVELOPMENT_GUIDE.md — the team's onboarding doc.

Building and testing

cd compiler
yarn install
yarn snap                      # run all golden-file tests
yarn snap -p simple.js -d      # run one fixture, debug mode (prints HIR after each pass)
yarn snap -u                   # update goldens
yarn snap compile <path>       # compile an arbitrary file outside the fixture set
yarn snap minimize <path>      # minimize a failing file to its smallest reproduction
yarn workspace babel-plugin-react-compiler lint

The full test suite is golden-file based — fixtures in compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/ produce .expect.md files with the expected HIR after each pass and the expected emitted JS.

Relationship with the runtime

The compiler is separate from the runtime in the build sense (different yarn workspace, different lint, different formatter version) but not in the version sense — its output is meant to be consumed by react itself. The runtime exposes react/compiler-runtime (= packages/react/src/ReactCompilerRuntime.js) as a public entry point that compiled code imports.

The runtime tree's eslint-plugin-react-hooks v7+ also imports compiler analyses (via compiler/packages/babel-plugin-react-compiler) to power its newer rules. See packages/eslint-plugin-react-hooks.