Contributing to React Compiler

Thank you for your interest in contributing to React Compiler! This guide will help you set up your development environment and understand the contribution workflow.

Getting Started

Prerequisites

Node.js: Version 18 or higher
Yarn: Package manager (v1 or v3+)
Git: For version control
Editor: VS Code recommended (with TypeScript support)

Clone the Repository

git clone https://github.com/facebook/react.git
cd react/compiler

Install Dependencies

yarn install

Build the Compiler

# Build all packages
yarn build

# Build and watch for changes
yarn watch

Development Workflow

Running Tests

React Compiler uses a custom test runner called snap:

# Run all tests
yarn snap

# Run tests in watch mode
yarn snap --watch

# Run specific test pattern
yarn snap -p "pattern"

# Run with debug output
yarn snap -p "fixture-name" -d

# Update test snapshots
yarn snap -u

Test Fixtures

Test fixtures are located in:

packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/

Fixture types:

feature-name.js - Normal test case
feature-name.expect.md - Expected output
error.todo-*.js - Known limitation (graceful bailout)
error.bug-*.js - Known bug

Fixture format:

// @enableFeatureFlag:true
// Comment describing the test case
function Component(props) {
  // Test code
}

Adding a New Test

Create fixture file:

touch packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/my-feature.js

Write test code:

my-feature.js

// Tests that my feature works correctly
function MyComponent({ value }) {
  const result = myFeature(value);
  return <div>{result}</div>;
}

Generate expected output:

yarn snap -p my-feature -u

Verify output:

cat packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/my-feature.expect.md

Compiling Arbitrary Files

Test the compiler on any file:

# Compile and see output
yarn snap compile path/to/file.js

# Compile with debug output (shows all passes)
yarn snap compile --debug path/to/file.js

Minimizing Test Cases

Reduce a failing test to minimal reproduction:

# Minimize a file
yarn snap minimize path/to/file.js

# Minimize and update in-place
yarn snap minimize --update path/to/file.js

Code Structure

Key Directories

compiler/
├── packages/
│   ├── babel-plugin-react-compiler/     # Main compiler
│   │   ├── src/
│   │   │   ├── Babel/                     # Babel integration
│   │   │   ├── Entrypoint/                # Pipeline orchestration
│   │   │   ├── HIR/                       # HIR data structures
│   │   │   ├── SSA/                       # SSA passes
│   │   │   ├── TypeInference/             # Type system
│   │   │   ├── Inference/                 # Effect inference
│   │   │   ├── ReactiveScopes/            # Scope construction
│   │   │   ├── Optimization/              # Optimizations
│   │   │   ├── Validation/                # Validation passes
│   │   │   └── __tests__/                 # Test fixtures
│   │   └── docs/passes/               # Pass documentation
│   ├── eslint-plugin-react-compiler/  # ESLint plugin
│   ├── react-compiler-runtime/        # Runtime helpers
│   └── snap/                          # Test runner
├── docs/                              # Documentation
└── scripts/                           # Build scripts

Important Files

src/Entrypoint/Pipeline.ts - Main compilation pipeline
src/HIR/HIR.ts - HIR type definitions
src/HIR/Environment.ts - Configuration schema
src/CompilerError.ts - Error handling

Making Changes

Modifying a Pass

Before modifying a pass, read its documentation:

packages/babel-plugin-react-compiler/docs/passes/

Each pass has detailed documentation explaining:

Purpose and invariants
Input/output guarantees
Algorithm description
Edge cases

Example workflow:

Find the pass:

# List all pass docs
ls packages/babel-plugin-react-compiler/docs/passes/

Read the documentation:

cat packages/babel-plugin-react-compiler/docs/passes/08-inferMutationAliasingEffects.md

Locate the implementation:

src/Inference/InferMutationAliasingEffects.ts

Make your changes
Add test cases
Run tests:

yarn snap

Adding a New Pass

Create the pass file:

src/MyCategory/MyNewPass.ts

import { HIRFunction } from '../HIR';

export function myNewPass(fn: HIRFunction): void {
  // Implementation
}

Add to pipeline:

src/Entrypoint/Pipeline.ts

import { myNewPass } from '../MyCategory/MyNewPass';

// In runWithEnvironment function:
myNewPass(hir);
log({kind: 'hir', name: 'MyNewPass', value: hir});

Add documentation:

touch packages/babel-plugin-react-compiler/docs/passes/XX-myNewPass.md

Write tests:

touch src/__tests__/fixtures/compiler/my-new-pass-basic.js

Adding Configuration Options

Update schema:

src/HIR/Environment.ts

export const EnvironmentConfigSchema = z.object({
  // ... existing options
  
  myNewOption: z.boolean().default(false),
});

Use in code:

if (env.config.myNewOption) {
  // Apply optimization
}

Document in configuration.mdx

Error Handling

Error Types

import { CompilerError } from '../CompilerError';

// Graceful bailout for unsupported feature
CompilerError.throwTodo({
  reason: 'Support [feature description]',
  loc: node.loc,
});

// Hard error for invalid state
CompilerError.invariant(condition, {
  reason: 'Expected [condition]',
  loc: node.loc,
});

// Validation error for rule violation
return Err(
  new CompilerError({
    kind: 'InvalidReact',
    reason: 'Component violates Rules of React',
    loc: node.loc,
  })
);

When to Use Each

throwTodo: Known limitation, expected pattern that’s not yet supported
invariant: Unexpected state indicating a compiler bug
InvalidReact: User code violates React’s rules
InvalidJS: Syntactically invalid JavaScript

Debugging

Debug Output

Run tests with debug logging:

yarn snap -p my-test -d

This shows HIR after each pass.

Custom Logger

Create a debug logger:

const logger = {
  debugLogIRs(value) {
    console.log(`[${value.kind}] ${value.name}`);
    if (value.kind === 'hir') {
      console.log(prettyPrint(value.value));
    }
  },
};

Breakpoints

Set breakpoints in VS Code:

Open file in editor
Click left of line number to add breakpoint
Run test in debug mode: F5

Print HIR

Use pretty printer:

import { printHIR } from '../HIR/PrintHIR';

console.log(printHIR(hir));

Submitting Changes

Commit Guidelines

React Compiler uses Sapling (similar to Mercurial):

# Check status
sl status

# Add new/removed files
sl addremove

# Commit changes
sl commit -m "Brief description

Detailed explanation of changes.

Test plan: How you tested the changes."

Commit Message Format

[compiler] Brief description (50 chars)

Detailed explanation of:
- What changed
- Why it changed
- How it works

Test plan:
- Added test fixtures
- Ran yarn snap
- Tested on real-world code

Opening a Pull Request

Push your changes:

sl push

Create PR on GitHub:

Base: facebook/react:main
Title: Brief description
Description: Detailed explanation + test plan

Address review feedback
Wait for CI to pass

PR Checklist

Tests added for new functionality
All tests passing (yarn snap)
Pass documentation updated (if modifying pass)
Configuration documented (if adding options)
Examples added to fixtures
Commit message follows format
No unrelated changes

Code Style

TypeScript

Use explicit types for public APIs
Prefer interface over type for objects
Use const over let when possible
Avoid any - use unknown instead

Naming Conventions

Files: PascalCase for classes, camelCase for utilities
Variables: camelCase
Types: PascalCase
Constants: UPPER_SNAKE_CASE
Private fields: #privateField (private class fields)

Formatting

Code is automatically formatted. Run:

yarn lint --fix

Getting Help

Resources

Documentation: Read docs/ and docs/passes/
CLAUDE.md: Compiler knowledge base
GitHub Issues: Search existing issues
Discord: React Compiler channel

Asking Questions

When asking for help, provide:

What you’re trying to do
What you’ve tried
Minimal reproduction (test fixture)
Expected vs actual behavior
Error messages (full output)

Common Tasks

Update Expected Output

yarn snap -u

Run Specific Category

yarn snap -p "error.*"

Check Type Errors

yarn tsc --noEmit

Run Linter

yarn lint

Build for Production

yarn build

Advanced Topics

Custom Test Runner

The snap runner is in packages/snap/. It:

Discovers fixtures
Compiles code
Generates expected output
Executes code in both versions
Compares results

Compiler Profiling

Enable timing:

ENABLE_REACT_COMPILER_TIMINGS=1 yarn snap

Memory Profiling

Use Node inspector:

node --inspect-brk $(yarn bin)/snap

Open Chrome DevTools and profile.

Best Practices

Writing Tests

One concept per fixture - Each test should validate one behavior
Descriptive names - Name clearly indicates what’s tested
Comments - Explain why behavior is expected
Edge cases - Test boundary conditions

Code Quality

Keep passes focused - Each pass should do one thing well
Document invariants - State assumptions clearly
Error messages - Make them actionable
Performance - Avoid O(n²) algorithms when possible

Review Process

Self-review - Review your own changes first
Test thoroughly - Run on real-world code
Explain changes - Help reviewers understand
Respond promptly - Address feedback quickly

Next Steps

Architecture

Understand the compiler pipeline

HIR

Learn the intermediate representation

Optimization Passes

Study specific passes

Configuration

Configuration options reference

License

By contributing to React Compiler, you agree that your contributions will be licensed under the MIT license.

​Contributing to React Compiler

​Getting Started

​Prerequisites

​Clone the Repository

​Install Dependencies

​Build the Compiler

​Development Workflow

​Running Tests

​Test Fixtures

​Adding a New Test

​Compiling Arbitrary Files

​Minimizing Test Cases

​Code Structure

​Key Directories

​Important Files

​Making Changes

​Modifying a Pass

​Adding a New Pass

​Adding Configuration Options

​Error Handling

​Error Types

​When to Use Each

​Debugging

​Debug Output

​Custom Logger

​Breakpoints

​Print HIR

​Submitting Changes

​Commit Guidelines

​Commit Message Format

​Opening a Pull Request

​PR Checklist

​Code Style

​TypeScript

​Naming Conventions

​Formatting

​Getting Help

​Resources

​Asking Questions

​Common Tasks

​Update Expected Output

​Run Specific Category

​Check Type Errors

​Run Linter

​Build for Production

​Advanced Topics

​Custom Test Runner

​Compiler Profiling

​Memory Profiling

​Best Practices

​Writing Tests

​Code Quality

​Review Process

​Next Steps