Compiler Overview & Pipeline

React Compiler optimizes React applications so that only the minimal parts of components and hooks re-render when state changes. It also checks that components and hooks follow the Rules of React.

It exists to reduce the need for manual memoization in application code. The compiler can remove manual useMemo and useCallback calls, validate the function, and produce a compiled function for the surrounding transform.

Sources: compiler/README.md:1-4, compiler/packages/babel-plugin-react-compiler/src/Inference/DropManualMemoization.ts:380-391, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:582-604

Core concepts

Compiler

React Compiler optimizes React applications to minimize unnecessary component and hook re-renders, and validates that components and hooks follow the Rules of React.

Sources: compiler/README.md:1-4

Manual memoization

Manual memoization is memoization performed through the useMemo and useCallback APIs. The compiler has a pass that removes these calls: useMemo(fn, deps) becomes a call to fn(), while useCallback(fn, deps) becomes a load of fn.

This is the problem the compiler addresses compared with the older manual approach: developers do not need to preserve every manual memoization call as the final implementation, while the compiler can still validate that useMemo is used for a returned value rather than arbitrary side effects.

Sources: compiler/packages/babel-plugin-react-compiler/src/Inference/DropManualMemoization.ts:380-391, compiler/crates/react_compiler_optimization/src/drop_manual_memoization.rs:6-13, compiler/packages/babel-plugin-react-compiler/src/Inference/DropManualMemoization.ts:388-391, compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateUseMemo.ts:127-139

HIR

HIR is the representation built by lower from a function and logged before subsequent pipeline passes run.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:154-161

Reactive function

A reactive function is a later compiler representation that the pipeline can expose separately from the original AST and HIR. CompilerPipelineValue distinguishes ast, hir, reactive, and debug values so intermediate results can be inspected.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:105-109

How a function enters the pipeline

The public per-function entrypoint is compileFn. It accepts a function path, compiler configuration, React function type, output mode, program context, logger, filename, and source code, then delegates directly to run.

run first finds context identifiers and constructs an Environment containing the function, configuration, mode, logger, filename, source, and program context. It then passes the function and environment to runWithEnvironment.

The call order from the entrypoint into the environment-backed pipeline is:

The important boundary is that run prepares compilation state, while runWithEnvironment owns the ordered transformations after that state exists.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:582-604, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:111-142, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:148-580

Ordered pipeline stages

The pipeline starts by lowering the function into HIR, then prunes possible throws and validates context-variable assignments and manual memoization. If configured, it drops manual memoization before inlining immediately invoked functions and merging consecutive blocks.

Next, it checks identifier and control-flow consistency, enters SSA form, removes redundant phi nodes, propagates constants, and infers types. These stages reshape the intermediate representation so later analyses can reason about values and assignments more precisely.

Validation is conditional on the environment. When enabled, the pipeline can validate hook usage and reject capitalized calls according to configuration. It then optimizes props method calls, analyzes functions, and infers mutation and aliasing effects.

For server-rendered output, the pipeline adds an SSR-specific optimization. It then performs dead-code elimination, prunes possible throws again, and infers mutation-aliasing ranges before additional validation of locals and mutable ranges.

The visible pipeline can be summarized as:

Each stage can also be logged through log, which forwards a CompilerPipelineValue to the configured debug logger. This makes HIR and other intermediate representations observable without changing the transformation order.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:157-181, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:183-201, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:203-221, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:223-248, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:148-580, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:154-156

What the compiler emits

The compiler does not emit only diagnostic metadata. compileFn returns a CodegenFunction result from run, and the Rust pipeline describes that result as the compiled function used for AST replacement.

At the same time, metadata-like pipeline values exist for inspection: the compiler can record AST, HIR, reactive, and debug representations. Those values explain what tooling can display during compilation, but they are not the only output of the compiler.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:582-604, compiler/crates/react_compiler/src/entrypoint/program.rs:2043-2061, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:105-109

How it connects

The pipeline is exposed through the Babel compiler package, whose package entrypoint is dist/index.js; this is the integration surface described by Babel Plugin Integration

For the representations and scope reasoning behind the middle of the pipeline, continue to Compiler HIR & Passes The mutation and aliasing analyses connect directly to Mutability Inference & Aliasing

The validation stages are expanded in Compiler Validation & Diagnostics The parallel implementation work is covered by Compiler Rust Port

Sources: compiler/packages/babel-plugin-react-compiler/package.json:1-8, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Pipeline.ts:217-221

Key takeaways

• React Compiler minimizes unnecessary React re-renders and validates the Rules of React.
• Manual useMemo and useCallback calls can be removed and replaced with compiler-managed behavior.
• A function is lowered to HIR before normalization, SSA, inference, analysis, validation, and code generation.
• The compiler returns a compiled function for AST replacement; pipeline values additionally support debugging and inspection.