Compiler Rust Port

Relevant source files

• compiler/Cargo.lock
• compiler/Cargo.toml
• compiler/README.md
• compiler/apps/playground/public/site.webmanifest
• compiler/crates/react_compiler/src/entrypoint/imports.rs
• compiler/crates/react_compiler/src/entrypoint/program.rs
• compiler/crates/react_compiler_ast/Cargo.toml
• compiler/crates/react_compiler_ast/src/literals.rs
• compiler/crates/react_compiler_diagnostics/src/js_string.rs
• compiler/crates/react_compiler_diagnostics/src/lib.rs
• compiler/crates/react_compiler_hir/src/lib.rs
• compiler/crates/react_compiler_hir/src/print.rs
• compiler/crates/react_compiler_inference/src/memoize_fbt_and_macro_operands_in_same_scope.rs
• compiler/crates/react_compiler_lowering/src/build_hir.rs
• compiler/crates/react_compiler_lowering/src/identifier_loc_index.rs
• compiler/crates/react_compiler_optimization/src/constant_propagation.rs
• compiler/crates/react_compiler_reactive_scopes/src/codegen_reactive_function.rs
• compiler/docs/DESIGN_GOALS.md
• compiler/packages/babel-plugin-react-compiler/src/Inference/MUTABILITY_ALIASING_MODEL.md
• compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-mutate-phi-which-could-be-frozen.expect.md
• compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-mutate-phi-which-could-be-frozen.js
• compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.todo-for-loop-with-context-variable-iterator.expect.md
• compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.todo-for-loop-with-context-variable-iterator.js
• compiler/scripts/profile-rust-port.ts

The React Compiler Rust Port is an experimental rewrite of the core React Compiler logic in Rust. This initiative aims to improve compilation performance and leverage Rust's memory safety and concurrency features. The port is organized within the compiler/crates/ workspace and integrates with the existing JavaScript-based ecosystem via a NAPI bridge.

---

Repository Structure and Workspace

The Rust implementation is housed within the compiler/ sub-monorepo. The Rust components are managed as a Cargo workspace defined in the root of the compiler directory. The workspace groups multiple crates and external dependencies and is declared in compiler/Cargo.toml:

• The workspace members include "crates/*" for all Rust crates in the workspace.
• This structure supports integration with the napi crate used for bridging Rust and Node.js.

Component	Location	Description
Cargo Workspace	compiler/Cargo.toml	Defines Rust crates and workspace members including crates/* and their dependencies compiler/Cargo.toml1-5
Compiler Core	compiler/crates/react_compiler	Main entrypoint orchestrating the compilation pipeline, a Rust port of the TypeScript Program.ts compiler/crates/react_compiler/src/entrypoint/program.rs6-16
AST Definitions	compiler/crates/react_compiler_ast	Rust representation of the JavaScript/Babel AST compiler/crates/react_compiler_ast/Cargo.toml1-4
Diagnostics	compiler/crates/react_compiler_diagnostics	Common error and logging infrastructure for Rust crates compiler/crates/react_compiler_ast/Cargo.toml7

This modular design enables clear separation of responsibilities between the parsing/AST model, compiler logic, diagnostics, and optimization passes, all coordinated by the core compilation entrypoint.

Sources: compiler/Cargo.toml1-5 compiler/crates/react_compiler/src/entrypoint/program.rs6-16 compiler/crates/react_compiler_ast/Cargo.toml1-7

---

Arena-Based Data Model

The Rust port employs an arena-based data model to represent the High-level Intermediate Representation (HIR) used throughout compilation. Unlike the TypeScript compiler’s potentially more object/cyclic graph-based model, the Rust port uses indices (newtyped integer IDs) referencing arena-allocated entities. This design:

• Simplifies memory management, avoiding complex Rust borrow checker issues with cyclic references.
• Enables efficient indexing and fast lookups crucial for compiler performance.
• Mirrors common Rust compiler data models for control flow graphs and SSA.

Key Identifiers and Types

These integer-indexed newtypes serve as stable, type-safe handles for core code entities:

Identifier	Meaning	Defined in
IdentifierId	Unique variable/identifier index in HIR	react_compiler_hir::IdentifierId react_compiler_hir/src/lib.rs29
ScopeId	Unique reactive scope index	react_compiler_hir::ScopeId react_compiler_hir/src/lib.rs44
BlockId	Basic block index in Control Flow Graph	react_compiler_hir::BlockId react_compiler_hir/src/lib.rs26
FunctionId	Unique function index discovered during compilation	react_compiler_hir::FunctionId react_compiler_hir/src/lib.rs50
JsString	UTF-16 safe string type handling lone surrogates	In diagnostics crate, handles ill-formed UTF-16 for JS strings compiler/crates/react_compiler_diagnostics/src/js_string.rs1-34

Data Representation Architecture

This model aligns with the architecture described in the React Compiler design principles, representing nodes as indices for fast access in a flat arena rather than nested pointers.

Sources: compiler/crates/react_compiler_hir/src/lib.rs25-50 compiler/crates/react_compiler_hir/src/lib.rs158-174 compiler/crates/react_compiler_diagnostics/src/js_string.rs1-34

---

The NAPI Bridge

To integrate the Rust compiler with the Babel-based React Compiler ecosystem, the Rust code exposes APIs using napi-rs, which generates Node.js native modules via N-API for seamless interoperability.

• This bridge takes Babel AST nodes in JSON format from JavaScript, deserializes them to Rust AST structures (react_compiler_ast), runs compilation passes, and returns transformed AST back to Babel as JSON.
• The Rust crate for native interface handling depends on the napi and napi-derive crates compiler/Cargo.lock189-192

Compilation Pipeline Orchestration

The main entrypoint in Rust is program.rs within the react_compiler crate. It maps closely to the TypeScript Program.ts by orchestrating the compilation workflow:

1. Validation and Import Checking: Checks for disallowed imports and finds program-level suppressions [lines 10-70].
2. Function Discovery: Finds all functions (components/hooks) to compile in the program [lines 90-105].
3. Lowering: Transforms Babel AST into HIR by invoking the HirBuilder and lowering passes (in react_compiler_lowering crate) [see build_hir.rs].
4. Inference and Optimization:
   • Passes like memoize_fbt_and_macro_operands_in_same_scope identify macro operands and enforce memoization scoping [react_compiler_inference/src/memoize_fbt_and_macro_operands_in_same_scope.rs].
   • Constant propagation and other optimizations run in the react_compiler_optimization crate [constant_propagation.rs].
5. Code Generation: Converts the reactive function representation back into Babel-compatible AST using CodegenFunction in the react_compiler_reactive_scopes crate [codegen_reactive_function.rs].

Diagram: NAPI Data and Entity Flow

This pipeline enables tight integration with the existing Babel tooling while benefiting from Rust’s performance and correctness guarantees.

Sources: compiler/crates/react_compiler/src/entrypoint/program.rs1-63 compiler/crates/react_compiler_lowering/src/build_hir.rs1-24 compiler/crates/react_compiler_reactive_scopes/src/codegen_reactive_function.rs6-11 compiler/crates/react_compiler_optimization/src/constant_propagation.rs1-42 compiler/Cargo.lock189-192

---

Testing via Snap Harness

Testing the Rust port uses the established fixtures and snapshot harness shared with the TypeScript compiler implementation to ensure correctness and parity.

Snap Harness Integration Details

• --rust Flag: When running the compiler test suite, this flag directs the test harness to invoke the Rust compiler instead of the TypeScript one, enabling direct comparison [test scripts, implied].
• IdentifierLocIndex: The Rust code builds an index from identifier node IDs to source locations (positions in the source code), used to mirror behavior like TypeScript's gatherCapturedContext for consistent diagnostics and handling compiler/crates/react_compiler_lowering/src/identifier_loc_index.rs1-48
• JsString Normalization: The JsString type handles the representation of potentially ill-formed UTF-16 strings from JavaScript, including lone surrogates that are encoded as __SURROGATE_XXXX__ markers in JSON, ensuring snapshot parity by matching the original source compiler/crates/react_compiler_diagnostics/src/js_string.rs8-12
• Diagnostics and Debug Printing:
  • The react_compiler_hir::print::PrintFormatter module provides debug formatting utilities to print HIR and reactive functions uniformly compiler/crates/react_compiler_hir/src/print.rs1-15
  • It includes exact replication of JavaScript number formatting for floating point values using the format_js_number function compiler/crates/react_compiler_hir/src/lib.rs113-151

This shared infrastructure guarantees that both Rust and TypeScript implementations produce equivalent diagnostics and transformed code snapshots.

Sources: compiler/crates/react_compiler_lowering/src/identifier_loc_index.rs1-48 compiler/crates/react_compiler_diagnostics/src/js_string.rs8-12 compiler/crates/react_compiler_hir/src/print.rs1-15 compiler/crates/react_compiler_hir/src/lib.rs113-151

---

Summary

The Rust port of the React Compiler represents a major engineering effort to rewrite the compiler's core pipeline in Rust while preserving the existing semantics, interfaces, and developer experience from the TypeScript version. Key aspects include:

• A modular Cargo workspace in compiler/crates dividing the compiler into AST, core logic, diagnostics, and optimization crates.
• An arena-based HIR data model using integer identifiers for efficient and safe indexing.
• A NAPI bridge enabling tight integration with Babel tooling and JavaScript AST flows.
• Comprehensive snapshot-based tests with a --rust flag to verify strict parity with the TypeScript compiler outputs.

The Rust port lays the groundwork for potential improvements in performance, memory safety, and future extensibility of the React Compiler.

---

Additional Mermaid Diagram: Mapping Natural Language Terms to Code Entities

---

References to Critical Files

• Workspace and core orchestration:
  compiler/Cargo.toml:1-5
compiler/crates/react_compiler/src/entrypoint/program.rs:6-16

• Core arena data types:
  compiler/crates/react_compiler_hir/src/lib.rs:25-50
compiler/crates/react_compiler_hir/src/lib.rs:158-174

• Diagnostics and string handling:
  compiler/crates/react_compiler_diagnostics/src/js_string.rs:1-34

• Lowering AST to HIR and identifier indexing:
  compiler/crates/react_compiler_lowering/src/build_hir.rs:1-24
compiler/crates/react_compiler_lowering/src/identifier_loc_index.rs:1-48

• Optimization passes:
  compiler/crates/react_compiler_optimization/src/constant_propagation.rs:1-42

• Code generation:
  compiler/crates/react_compiler_reactive_scopes/src/codegen_reactive_function.rs:6-11

• Inference passes (e.g., memoize FBT operands):
  compiler/crates/react_compiler_inference/src/memoize_fbt_and_macro_operands_in_same_scope.rs:98-101

• HIR debug printing and number formatting:
  compiler/crates/react_compiler_hir/src/print.rs:1-15
compiler/crates/react_compiler_hir/src/lib.rs:113-151

Sources: All files referenced above