Rust Port Step 5: Babel Plugin (babel-plugin-react-compiler-rust)

Goal

Create a new, minimal Babel plugin package (babel-plugin-react-compiler-rust) that serves as a thin JavaScript shim over the Rust compiler. The JS side does only three things:

1. Pre-filter: Quick name-based scan for potential React functions (capitalized or hook-like names)
2. Invoke Rust: Serialize the Babel AST, scope info, and resolved options to JSON; call the Rust compiler via NAPI
3. Apply result: Replace the program AST with the Rust-returned AST and forward logger events

All complex logic — function detection, compilation mode decisions, directives, suppressions, gating rewrites, import insertion, outlined functions — lives in Rust. This ensures the logic is implemented once and reused across future OXC and SWC integrations.

Current status: Implementation complete. All entrypoint logic ported to Rust: compile_program orchestration, shouldSkipCompilation, findFunctionsToCompile, getReactFunctionType/getComponentOrHookLike (with all name heuristics, callsHooksOrCreatesJsx, returnsNonNode, isValidComponentParams), directive parsing, suppression detection/filtering, ProgramContext (uid generation, import tracking), gating rewrites, import insertion. The actual per-function compilation (compileFn) returns a skip event pending full pipeline implementation.

Prerequisites: rust-port-0001-babel-ast.md (complete), rust-port-0002-scope-types.md (complete), core compilation pipeline in Rust (in progress).

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│  Babel                                                  │
│                                                         │
│  1. Parse source → Babel AST                            │
│  2. babel-plugin-react-compiler-rust                    │
│     ┌─────────────────────────────────────────────┐     │
│     │  JS Shim (~50 lines)                        │     │
│     │                                             │     │
│     │  a) Pre-filter: any capitalized/hook fns?   │     │
│     │  b) Pre-resolve: sources filter, reanimated,│     │
│     │     isDev → serializable options             │     │
│     │  c) Extract scope tree (rust-port-0002)     │     │
│     │  d) JSON.stringify(ast, scope, options)     │     │
│     │  e) Call Rust via NAPI                      │     │
│     │  f) Parse result, forward logger events     │     │
│     │  g) Replace program AST if changed          │     │
│     └──────────────┬──────────────────────────────┘     │
│                    │ JSON                                │
│     ┌──────────────▼──────────────────────────────┐     │
│     │  Rust Compiler (via napi-rs)                │     │
│     │                                             │     │
│     │  - shouldSkipCompilation                    │     │
│     │  - findFunctionsToCompile                   │     │
│     │    (all compilation modes, directives,      │     │
│     │     forwardRef/memo, suppressions, etc.)    │     │
│     │  - compileFn (full pipeline)                │     │
│     │  - gating rewrites                          │     │
│     │  - import insertion                         │     │
│     │  - outlined function insertion              │     │
│     │  - panicThreshold handling                  │     │
│     │                                             │     │
│     │  Returns: modified AST | null + events      │     │
│     └─────────────────────────────────────────────┘     │
│                                                         │
│  3. Babel continues with modified (or original) AST     │
└─────────────────────────────────────────────────────────┘

Why This Split

The guiding principle is implement once in Rust, integrate thinly per tool. The current TS plugin has ~1300 lines of complex entrypoint logic (Program.ts, Imports.ts, Gating.ts, Suppression.ts, Reanimated.ts, Options.ts). If this logic stayed in JS, it would need to be reimplemented for OXC and SWC integrations. By moving it all to Rust:

• Babel shim: ~50 lines of JS
• Future OXC integration: ~50 lines of Rust (native Traverse trait, serialize to same JSON format)
• Future SWC integration: ~50 lines of Rust (native VisitMut trait, serialize to same JSON format)

Each integration only needs to: (1) do a cheap pre-filter, (2) serialize AST + scope to the Babel JSON format, (3) call compile(), (4) apply the result.

Rust Public API

The Rust compiler exposes a single entry point. This extends the existing planned API from rust-port-notes.md with structured results:

/// Main entry point for the React Compiler.
///
/// Receives a full program AST, scope information, and resolved options.
/// Returns a CompileResult containing either a modified AST or null,
/// along with structured logger events.
#[napi]
pub fn compile(
    ast_json: String,
    scope_json: String,
    options_json: String,
) -> napi::Result<String> {
    let ast: babel_ast::File = serde_json::from_str(&ast_json)?;
    let scope: ScopeInfo = serde_json::from_str(&scope_json)?;
    let opts: PluginOptions = serde_json::from_str(&options_json)?;

    let result = react_compiler::compile_program(ast, scope, opts);

    Ok(serde_json::to_string(&result)?)
}

Result Type

#[derive(Serialize)]
#[serde(tag = "kind")]
pub enum CompileResult {
    /// Compilation succeeded (or no functions needed compilation).
    /// `ast` is None if no changes were made to the program.
    Success {
        ast: Option<babel_ast::File>,
        events: Vec<LoggerEvent>,
    },
    /// A fatal error occurred and panicThreshold dictates it should throw.
    /// The JS shim re-throws this as a CompilerError.
    Error {
        error: CompilerErrorInfo,
        events: Vec<LoggerEvent>,
    },
}

#[derive(Serialize)]
pub struct CompilerErrorInfo {
    pub reason: String,
    pub description: Option<String>,
    pub details: Vec<CompilerErrorDetail>,
}

Logger Events

Rust returns the same structured events as the current TS compiler. The JS shim forwards them to the user-provided logger:

#[derive(Serialize)]
#[serde(tag = "kind")]
pub enum LoggerEvent {
    CompileSuccess {
        fn_loc: Option<SourceLocation>,
        fn_name: Option<String>,
        memo_slots: u32,
        memo_blocks: u32,
        memo_values: u32,
        pruned_memo_blocks: u32,
        pruned_memo_values: u32,
    },
    CompileError {
        fn_loc: Option<SourceLocation>,
        detail: CompilerErrorDetail,
    },
    CompileSkip {
        fn_loc: Option<SourceLocation>,
        reason: String,
        loc: Option<SourceLocation>,
    },
    CompileUnexpectedThrow {
        fn_loc: Option<SourceLocation>,
        data: String,
    },
    PipelineError {
        fn_loc: Option<SourceLocation>,
        data: String,
    },
    // Note: Timing events are handled on the JS side (performance.mark/measure)
}

Resolved Options

Options that involve JS functions or runtime checks (like sources filter, Reanimated detection) cannot cross the NAPI boundary. The JS shim pre-resolves these before calling Rust:

JS-Side Resolution

Serializable Options (Passed Directly to Rust)

// Options that serialize directly to Rust
interface RustPluginOptions {
    // Pre-resolved by JS
    shouldCompile: boolean;
    enableReanimated: boolean;
    isDev: boolean;
    filename: string | null;

    // Passed through as-is
    compilationMode: 'infer' | 'syntax' | 'annotation' | 'all';
    panicThreshold: 'all_errors' | 'critical_errors' | 'none';
    target: '17' | '18' | '19' | { kind: 'donotuse_meta_internal'; runtimeModule: string };
    gating: { source: string; importSpecifierName: string } | null;
    dynamicGating: { source: string } | null;
    noEmit: boolean;
    outputMode: 'ssr' | 'client' | 'lint' | null;
    eslintSuppressionRules: string[] | null;
    flowSuppressions: boolean;
    ignoreUseNoForget: boolean;
    customOptOutDirectives: string[] | null;
    environment: EnvironmentConfig;
}

JS Shim: babel-plugin-react-compiler-rust

Package Structure

compiler/packages/babel-plugin-react-compiler-rust/
    package.json
    tsconfig.json
    src/
        index.ts          # Babel plugin entry point (main export)
        BabelPlugin.ts    # Program visitor, pre-filter, bridge call
        prefilter.ts      # Name-based React function detection
        bridge.ts         # NAPI invocation, JSON serialization
        scope.ts          # Babel scope → ScopeInfo extraction (from rust-port-0002)
        options.ts        # Option resolution (pre-resolve JS-only options)

BabelPlugin.ts — Babel Plugin Entry Point

import type * as BabelCore from '@babel/core';
import {hasReactLikeFunctions} from './prefilter';
import {compileWithRust} from './bridge';
import {extractScopeInfo} from './scope';
import {resolveOptions, type PluginOptions} from './options';

export default function BabelPluginReactCompilerRust(
    _babel: typeof BabelCore,
): BabelCore.PluginObj {
    return {
        name: 'react-compiler-rust',
        visitor: {
            Program: {
                enter(prog, pass): void {
                    const filename = pass.filename ?? null;

                    // Step 1: Resolve options (pre-resolve JS-only values)
                    const opts = resolveOptions(pass.opts, pass.file, filename);

                    // Step 2: Quick bail — should we compile this file at all?
                    if (!opts.shouldCompile) {
                        return;
                    }

                    // Step 3: Pre-filter — any potential React functions?
                    if (!hasReactLikeFunctions(prog)) {
                        return;
                    }

                    // Step 4: Extract scope info
                    const scopeInfo = extractScopeInfo(prog);

                    // Step 5: Call Rust compiler
                    const result = compileWithRust(
                        prog.node,
                        scopeInfo,
                        opts,
                        pass.file.ast.comments ?? [],
                    );

                    // Step 6: Forward logger events
                    if (pass.opts.logger && result.events) {
                        for (const event of result.events) {
                            pass.opts.logger.logEvent(filename, event);
                        }
                    }

                    // Step 7: Handle result
                    if (result.kind === 'error') {
                        // panicThreshold triggered — throw
                        const err = new Error(result.error.reason);
                        // Attach details for CompilerError compatibility
                        (err as any).details = result.error.details;
                        throw err;
                    }

                    if (result.ast != null) {
                        // Replace the entire program body with Rust's output
                        prog.replaceWith(result.ast);
                        prog.skip(); // Don't re-traverse
                    }
                },
            },
        },
    };
}

prefilter.ts — Name-Based Pre-Filter

The pre-filter is intentionally loose. It checks only whether any function in the program has a name that could be a React component or hook. False positives (like ParseURL or FormatDate) are acceptable — Rust will quickly determine these aren't React functions and return null.

import {NodePath} from '@babel/core';
import * as t from '@babel/types';

/**
 * Quick check: does this program contain any functions with names that
 * could be React components (capitalized) or hooks (useXxx)?
 *
 * This is intentionally loose — Rust handles the precise detection.
 * We just want to avoid serializing files that definitely have no
 * React functions (e.g., pure utility modules, CSS-in-JS, configs).
 */
export function hasReactLikeFunctions(
    program: NodePath<t.Program>,
): boolean {
    let found = false;
    program.traverse({
        // Skip classes — their methods are not compiled
        ClassDeclaration(path) { path.skip(); },
        ClassExpression(path) { path.skip(); },

        FunctionDeclaration(path) {
            if (found) return;
            const name = path.node.id?.name;
            if (name && isReactLikeName(name)) {
                found = true;
                path.stop();
            }
        },
        FunctionExpression(path) {
            if (found) return;
            const name = inferFunctionName(path);
            if (name && isReactLikeName(name)) {
                found = true;
                path.stop();
            }
        },
        ArrowFunctionExpression(path) {
            if (found) return;
            const name = inferFunctionName(path);
            if (name && isReactLikeName(name)) {
                found = true;
                path.stop();
            }
        },
    });
    return found;
}

function isReactLikeName(name: string): boolean {
    return /^[A-Z]/.test(name) || /^use[A-Z0-9]/.test(name);
}

/**
 * Infer the name of an anonymous function expression from its parent
 * (e.g., `const Foo = () => {}` → 'Foo').
 */
function inferFunctionName(
    path: NodePath<t.FunctionExpression | t.ArrowFunctionExpression>,
): string | null {
    const parent = path.parentPath;
    if (
        parent.isVariableDeclarator() &&
        parent.get('init').node === path.node &&
        parent.get('id').isIdentifier()
    ) {
        return (parent.get('id').node as t.Identifier).name;
    }
    if (
        parent.isAssignmentExpression() &&
        parent.get('right').node === path.node &&
        parent.get('left').isIdentifier()
    ) {
        return (parent.get('left').node as t.Identifier).name;
    }
    return null;
}

bridge.ts — NAPI Bridge

// The napi-rs generated binding
import {compile as rustCompile} from '../native';

import type {ResolvedOptions} from './options';
import type {ScopeInfo} from './scope';
import type * as t from '@babel/types';

export interface CompileSuccess {
    kind: 'success';
    ast: t.Program | null;
    events: Array<LoggerEvent>;
}

export interface CompileError {
    kind: 'error';
    error: {
        reason: string;
        description?: string;
        details: Array<unknown>;
    };
    events: Array<LoggerEvent>;
}

export type CompileResult = CompileSuccess | CompileError;

export type LoggerEvent = {
    kind: string;
    [key: string]: unknown;
};

export function compileWithRust(
    ast: t.Program,
    scopeInfo: ScopeInfo,
    options: ResolvedOptions,
    comments: Array<t.Comment>,
): CompileResult {
    // Attach comments to the AST for Rust (Babel stores them separately)
    const astWithComments = {...ast, comments};

    const resultJson = rustCompile(
        JSON.stringify(astWithComments),
        JSON.stringify(scopeInfo),
        JSON.stringify(options),
    );

    return JSON.parse(resultJson) as CompileResult;
}

options.ts — Option Resolution

import type * as BabelCore from '@babel/core';
import {
    pipelineUsesReanimatedPlugin,
    injectReanimatedFlag,
} from './reanimated'; // Thin copy or import from existing

export interface ResolvedOptions {
    // Pre-resolved by JS
    shouldCompile: boolean;
    enableReanimated: boolean;
    isDev: boolean;
    filename: string | null;

    // Pass-through
    compilationMode: string;
    panicThreshold: string;
    target: unknown;
    gating: unknown;
    dynamicGating: unknown;
    noEmit: boolean;
    outputMode: string | null;
    eslintSuppressionRules: string[] | null;
    flowSuppressions: boolean;
    ignoreUseNoForget: boolean;
    customOptOutDirectives: string[] | null;
    environment: Record<string, unknown>;
}

export type PluginOptions = Partial<ResolvedOptions> & Record<string, unknown>;

export function resolveOptions(
    rawOpts: PluginOptions,
    file: BabelCore.BabelFile,
    filename: string | null,
): ResolvedOptions {
    // Resolve sources filter (may be a function)
    let shouldCompile = true;
    if (rawOpts.sources != null && filename != null) {
        if (typeof rawOpts.sources === 'function') {
            shouldCompile = rawOpts.sources(filename);
        } else if (Array.isArray(rawOpts.sources)) {
            shouldCompile = rawOpts.sources.some(
                (prefix: string) => filename.indexOf(prefix) !== -1,
            );
        }
    } else if (rawOpts.sources != null && filename == null) {
        shouldCompile = false; // sources specified but no filename
    }

    // Resolve reanimated check
    const enableReanimated =
        (rawOpts.enableReanimatedCheck !== false) &&
        pipelineUsesReanimatedPlugin(file.opts.plugins);

    // Resolve isDev
    const isDev =
        (typeof __DEV__ !== 'undefined' && __DEV__ === true) ||
        process.env['NODE_ENV'] === 'development';

    return {
        shouldCompile,
        enableReanimated,
        isDev,
        filename,
        compilationMode: rawOpts.compilationMode ?? 'infer',
        panicThreshold: rawOpts.panicThreshold ?? 'none',
        target: rawOpts.target ?? '19',
        gating: rawOpts.gating ?? null,
        dynamicGating: rawOpts.dynamicGating ?? null,
        noEmit: rawOpts.noEmit ?? false,
        outputMode: rawOpts.outputMode ?? null,
        eslintSuppressionRules: rawOpts.eslintSuppressionRules ?? null,
        flowSuppressions: rawOpts.flowSuppressions ?? true,
        ignoreUseNoForget: rawOpts.ignoreUseNoForget ?? false,
        customOptOutDirectives: rawOpts.customOptOutDirectives ?? null,
        environment: rawOpts.environment ?? {},
    };
}

What Rust Implements (from Program.ts and friends)

The following logic moves entirely from the TS entrypoint into Rust. Rust operates on the deserialized Babel AST and scope info, and returns a modified AST.

From Program.ts

From Imports.ts

From Gating.ts

From Suppression.ts

From Reanimated.ts

From Options.ts

NAPI Bridge Details

Technology: napi-rs

The bridge uses napi-rs to expose the Rust compile function to Node.js. This is the same approach used by SWC (@swc/core), Biome, and other Rust-based JS tools.

Serialization: JSON Strings

The bridge passes JSON strings across the NAPI boundary. This is the simplest approach and provides several benefits:

• Debuggable: JSON can be logged, inspected, and round-trip tested
• Consistent with existing infrastructure: The react_compiler_ast crate already handles JSON serde with all 1714 test fixtures passing
• No schema coupling: The JS side doesn't need generated bindings — just JSON.stringify/JSON.parse
• Adequate performance: For file-level granularity (one call per file), JSON serialization overhead is negligible compared to compilation time

Performance Considerations

The JSON serialization adds overhead, but it is bounded:

• Serialization: JSON.stringify of a typical program AST: ~1-5ms
• Deserialization in Rust: serde_json::from_str: ~1-5ms
• Re-serialization in Rust: serde_json::to_string of result: ~1-5ms
• Parse in JS: JSON.parse of result: ~1-5ms
• Total overhead: ~4-20ms per file
• Compilation time: Typically 50-500ms per file

The serialization overhead is 2-10% of total time. If this becomes a bottleneck, a future optimization could use Buffer passing with a binary format, but JSON is the right starting point.

Native Module Structure

compiler/packages/babel-plugin-react-compiler-rust/
    native/
        Cargo.toml          # napi-rs crate
        src/
            lib.rs          # #[napi] compile function
        build.rs            # napi-rs build script
    npm/                    # Platform-specific npm packages (generated by napi-rs)
        darwin-arm64/
        darwin-x64/
        linux-x64-gnu/
        win32-x64-msvc/
        ...

What Stays in JS vs What Moves to Rust

JS Side (Thin Shim)

Rust Side (Everything Else)

Cross-Tool Strategy (OXC, SWC)

This architecture is designed to support future OXC and SWC integrations with minimal per-tool code.

Common Boundary: Babel JSON AST

All integrations serialize to the same Babel JSON AST format that the react_compiler_ast crate expects. This means:

• OXC integration: A Rust transform that converts OXC's native AST → Babel JSON AST → calls compile() → converts result back to OXC AST. Since both are Rust, this can use the struct types directly (no JSON step needed for the Rust→Rust path — just type conversion).
• SWC integration: A Rust transform (native or WASM plugin) that converts SWC's AST → Babel JSON AST → calls compile() → converts result back.

Scope Abstraction

Each tool provides scope information differently:

• Babel: Scope tree object graph (extracted by JS, serialized to ScopeInfo)
• OXC: ScopeTree + SymbolTable from oxc_semantic (Rust-native, converted to ScopeInfo)
• SWC: Hygiene system (SyntaxContext/Mark) — requires building a scope tree equivalent

The ScopeInfo type from rust-port-0002 serves as the common abstraction. Each integration extracts its tool's scope model into this format.

Integration Size Comparison

Differences from Current TS Plugin

Behavioral Equivalence

The Rust plugin must produce identical output to the TS plugin for all inputs. The existing test infrastructure (yarn snap) can be used to verify this by running both plugins on the same fixtures and comparing output.

Known Differences

1. Timing events: Handled on the JS side using performance.mark/measure (not sent to Rust). The JS shim wraps the Rust call with timing markers.

2. CompilerError class: Rust returns a plain JSON error object. The JS shim constructs a CompilerError-compatible exception for Babel's error reporting.

3. debugLogIRs logger callback: This optional callback receives intermediate compiler pipeline values. Rust would need to serialize these if supported. Decision: Defer to a follow-up; not needed for initial parity.

4. Comments handling: Babel stores comments separately on file.ast.comments, not attached to AST nodes. The JS shim attaches comments to the program AST before serializing. Rust uses them for suppression detection.