Compiler Playground Internals

Overview

The React Compiler Playground is a diagnostic and educational tool built with Next.js. It provides a real-time environment to observe how the React Compiler transforms source code into optimized JavaScript. The playground integrates the babel-plugin-react-compiler with a web-based IDE experience, utilizing the Monaco Editor for code input and Graphviz (compiled to WASM) for visualizing the High-level Intermediate Representation (HIR) and Reactive Scopes.

Architecture and Transformation Pipeline

The playground mirrors the compiler's internal pipeline. When code is entered into the editor, it undergoes several transformation phases:

Parsing: Source code is parsed into an AST via Babel.
HIR Construction: The AST is converted into a High-level Intermediate Representation (HIR), a flat, control-flow graph (CFG) representation of the function.
Analysis & Optimization: Various passes are run over the HIR, including inference (types, effects, mutability) and dead code elimination.
Reactive Scopes Construction: The HIR is structured into reactive scopes—the units of memoization.
Code Generation: The final optimized JavaScript is generated, injecting useMemoCache calls (the "Memo Cache Sentinel" pattern).

Reactive Scope Pruning

A critical internal pass exposed in the playground's output is PruneNonEscapingScopes. This pass ensures that the compiler does not over-memoize values that do not impact the program's output or downstream reactivity.

Escape Analysis Logic

An identifier is considered to "escape" if:

It is directly returned by the function or transitively aliased by a return value.
It is passed as an argument to a hook (e.g., useEffect(callback, [])), as the hook may store the reference externally.

// Example: Pruning in action
function Component(props) {
   const a = {}; // Not aliased or returned: Pruned from memoization
   const b = {}; // Aliased by c: Memoized
   const c = [b]; // Returned: Memoized
   return c;
}

The algorithm operates in four stages:

Graph Construction: Maps IdentifierId to nodes describing the scopes and inputs involved in its creation.
Aliasing Classification: Identifies if values are definitely aliased (Arrays, Objects), conditionally aliased (Logical expressions), or unaliased (JSX).
Reachability Traversal: Starting from return values and hooks, the compiler marks all reachable dependencies as "escaping."
Pruning: Scopes whose outputs are not marked as escaping are removed.

Validation Layer

The playground surfaces errors from the compiler's validation suite. One primary check is ValidateNoCapitalizedCalls, which enforces React's component-calling conventions.

Capitalized Call Validation

The compiler restricts the invocation of capitalized functions unless they are explicitly allow-listed or follow a hook pattern. This prevents developers from calling components as regular functions (e.g., Header()) instead of using JSX (<Header />).

Configuration Interface:

export type EnvironmentConfig = {
  validateNoCapitalizedCalls?: Array<string>;
  hookPattern?: string; // Regex string for identifying custom hooks
  // ... other config
};

Internal Logic:

Global Allow-list: Common globals like Boolean, String, and Number are ignored.
Constant Exclusion: All-caps identifiers (e.g., CONSTANTS()) are ignored.
Property/Method Checks: The validator tracks LoadGlobal and PropertyLoad instructions to catch aliased capitalized functions.

Visualizations and Debugging

The playground uses specialized views to help developers debug the compiler's decision-making:

Monaco Editor Integration

The playground uses monaco-editor to provide a VS Code-like experience. It maps compiler diagnostics (errors and warnings) back to specific line/column offsets using the loc (location) data stored in the HIR.

WASM-based Graphviz Rendering

To visualize the CFG and Reactive Scopes, the playground utilizes a WebAssembly (WASM) port of Graphviz.

HIR View: Displays the basic blocks, terminal instructions (returns, jumps), and instruction IDs.
Reactive Scopes View: Highlights the boundaries of memoized blocks and their dependencies.

Compilation Metadata

The playground displays environment configurations used during the pass, such as:

@compilationMode: Whether the compiler is in infer or annotation mode.
@enablePreserveExistingMemoizationGuarantees: Whether the compiler should respect existing useMemo/useCallback boundaries.

Technical Implementation Details

API References for Internals

When exploring the playground's source or contributing, these types are central:

ReactiveFunction: The representation of a function after scope construction.
HIR: The flat representation used for most optimization passes.
IdentifierId: A unique numeric ID assigned to every variable in the program.
ScopeId: A unique ID for each memoization block.