Babel Plugin Integration

The Babel integration turns a Babel program into compiler input, resolves plugin options, and invokes compilation from the Program visitor. It also records optional timing data and converts compiler errors into source-aware Babel diagnostics.

This boundary exists so repositories can pass compiler options through Babel while preserving normal Babel traversal and error reporting. Function-level processing can skip a function, log a recoverable problem, or throw a non-recoverable compiler error instead of blindly rewriting the source.

Sources: compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:24-104, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Program.ts:650-663

Core concepts

Babel plugin entrypoint

A Babel plugin entrypoint is the function that returns a Babel visitor object; here it is BabelPluginReactCompiler, whose visitor handles the whole Program.

Sources: compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:24-104

Program compilation

Program compilation is the file-level operation that parses options and calls compileProgram with the AST, filename, comments, and original source text.

Sources: compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:24-104

Local directives

Local directives are function-body directives that processFn considers when deciding whether to compile, skip, log, or handle a function-level result.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Program.ts:601-626

Gating

Gating is emitting optimized and unoptimized function paths selected by an imported gating function. The gating option specifies the import source and imported function name used for that selection.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Options.ts:54-74

Compiler diagnostic

A compiler diagnostic is a categorized result with a reason, optional description, details, and optional suggestions; its severity is resolved from the diagnostic category.

Sources: compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:59-65, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:122-221

How Babel invokes the compiler

Babel invokes BabelPluginReactCompiler as a plugin in transformFromAstSync, passing the compiler options alongside the parsed AST.

The plugin installs a Program.enter handler because compilation is coordinated at the program boundary rather than by independently compiling each Babel node. The handler reads the filename, parses plugin options, derives development behavior, optionally injects a Reanimated flag, and then calls compileProgram.

The source passed to compileProgram includes pass.file.ast.comments and pass.file.code, so compilation receives both AST metadata and the original source needed for diagnostics.

When timing is enabled, the plugin marks the start and end of program processing using ENABLE_REACT_COMPILER_TIMINGS; on exit it measures the interval and sends the measurement to an optional logger.

Sources: compiler/packages/babel-plugin-react-compiler/src/Babel/RunReactCompilerBabelPlugin.ts:22-39, compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:24-104, compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:66-71, compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:72-99

How compilation is gated

At file scope, Babel supplies PluginOptions to the plugin, and the gating option can request a separate gated version of compiled functions. Its configuration contains a source and an importSpecifierName; the documented output imports that function and chooses between compiled and uncompiled versions.

At function scope, processFn explicitly accounts for local suppressions, opt-ins, and opt-outs before returning either a CodegenFunction or null. For expression-bodied functions, no body directives are available, so both local directive slots are set to null.

The Rust entrypoint describes the per-function gating rule more specifically: dynamic gating from a directive such as use memo if(identifier) takes precedence over plugin-level gating. This establishes the precedence, but the shown Babel excerpt does not define the complete directive grammar.

When gating is enabled for a function, insertGatedFunctionDeclaration adds the gating import and builds a conditional expression that selects the compiled function when the imported gate returns truthy, otherwise selecting the original function.

For a referenced function declaration, the rewrite preserves a callable wrapper: it creates a gating condition, renames the optimized and unoptimized implementations, and inserts a new function that calls one branch or the other.

For other function shapes, the rewrite places the conditional expression directly into the AST, converting a named function declaration into a const variable where necessary and handling export default separately.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Options.ts:54-74, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Program.ts:601-626, compiler/crates/react_compiler/src/entrypoint/program.rs:3994-4001, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Gating.ts:127-195, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Gating.ts:36-126

What happens when compilation is unsafe

Function compilation begins with tryCompileFunction. If it returns an error, processFn logs the error when the function has an opt-out directive; otherwise it calls handleError, then returns null without producing a compiled function.

The error model distinguishes actionable errors, warnings, hints, and disabled details through ErrorSeverity. Warnings cover cases such as unsupported syntax that do not necessarily indicate a product-code fault, while Off details are not reported.

Categories determine the summary shown to developers. Categories such as hooks, refs, purity, gating, syntax, and configuration produce Error, while incompatible libraries, preserved manual memoization, effect dependencies, and unsupported syntax produce Compilation Skipped.

CompilerDiagnostic can attach source locations and details, and its printer attempts to render a code frame from the original source. The Babel entrypoint catches CompilerError, calls withPrintedMessage with eslint: false, and rethrows the formatted error.

Long code frames are abbreviated: the formatter keeps configured lines above and below the location and inserts an ellipsis when the span exceeds CODEFRAME_MAX_LINES.

The result is therefore not “compile everything or fail the file.” A function can be skipped because of configuration or output mode, a recoverable problem can be logged, and a non-recoverable problem can propagate as a Babel error with a categorized message and source location.

Sources: compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Program.ts:650-663, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:37-57, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:438-444, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:565-611, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:122-221, compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:77-81, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:525-563, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Program.ts:657-663

How it connects

The Babel entrypoint hands compiler options and source context to the program-level compiler, which is the integration point described by Compiler Overview & Pipeline.

Function-level directives and gating decisions connect this page to Compiler Validation & Diagnostics, because diagnostics and skips are part of deciding whether a function can be safely transformed.

The generated gated branches connect to Reactive Scopes & Codegen, where compiled function output is produced before the Babel AST is rewritten.

The plugin is itself run inside repository Babel configurations and transform pipelines, which connects this page to Release, Build & Lint Scripts.

Sources: compiler/packages/babel-plugin-react-compiler/src/Babel/BabelPlugin.ts:24-104, compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts:565-611, compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Gating.ts:127-195

Key takeaways

• BabelPluginReactCompiler coordinates file-level compilation from Babel’s Program visitor.
• PluginOptions.gating adds a runtime choice between compiled and uncompiled function versions.
• processFn considers local directives and can return null without mutating the function.
• Unsafe compilation is categorized, logged or thrown according to handling rules, and formatted with source-aware diagnostics.
• Unsupported or incompatible cases can be reported as Compilation Skipped rather than treated as ordinary developer errors.