React — Administrator & Developer Guide

1. Architecture Overview

React is a monorepo containing the core UI library, multiple renderers, a scheduler, a compiler, developer tools, and supporting packages. The architecture separates the platform-agnostic reconciliation algorithm from platform-specific rendering, allowing React to target the DOM, native mobile, canvas, server-streamed HTML, and custom host environments through the same core engine.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        User Application                         │
│  Components, Hooks, JSX, Server/Client boundaries               │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                      react (core package)                       │
│  createElement, hooks API, Component/PureComponent,             │
│  createContext, memo, lazy, forwardRef, Suspense, Fragment,     │
│  Activity, ViewTransition, startTransition, cache, use          │
└────────────────────────────┬────────────────────────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐
│   react-dom    │ │ react-native-  │ │ react-test-renderer    │
│  (DOM renderer)│ │   renderer     │ │ react-art              │
│                │ │                │ │ react-noop-renderer     │
│ Client:        │ │ Fabric bridge  │ │ (testing & canvas)     │
│  createRoot    │ │ to native host │ └────────────────────────┘
│  hydrateRoot   │ └────────────────┘
│ Server:        │
│  renderTo*     │
│  Fizz (stream) │
└────────┬───────┘
         │
┌────────▼───────────────────────────────────────────────────────┐
│                    react-reconciler (Fiber)                     │
│  Work loop, fiber tree, hooks dispatcher, commit phase,        │
│  Suspense, transitions, lanes-based priority, effects          │
└────────────────────────────┬───────────────────────────────────┘
                             │
┌────────────────────────────▼───────────────────────────────────┐
│                        scheduler                               │
│  Cooperative scheduling: priority queue (min-heap),            │
│  MessageChannel-based yielding, 5 priority levels              │
└────────────────────────────────────────────────────────────────┘

     ┌──────────────────────────────────────────────────┐
     │         React Server Components (Flight)         │
     │  react-server + react-server-dom-{bundler}/      │
     │  Webpack, Turbopack, Parcel, ESM, Unbundled      │
     │  Server → Client streaming protocol              │
     └──────────────────────────────────────────────────┘

     ┌──────────────────────────────────────────────────┐
     │           React Compiler (babel-plugin)          │
     │  HIR → SSA → Type Inference → Reactive Scopes   │
     │  → Code Generation with automatic memoization    │
     └──────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Data Flow: Component Render Cycle

1. State update (setState/dispatch/transition)
   │
2. Scheduler enqueues work at appropriate priority lane
   │
3. Reconciler begins render phase (pure, interruptible)
   ├── Walks fiber tree top-down
   ├── Calls function components (runs hooks)
   ├── Diffs old vs new children (reconcileChildFibers)
   └── Builds work-in-progress fiber tree
   │
4. Commit phase (synchronous, non-interruptible)
   ├── Before-mutation: snapshot lifecycle, ref detach
   ├── Mutation: DOM insertions, updates, deletions
   └── Layout: useLayoutEffect, ref attachment, callbacks
   │
5. Passive effects (useEffect) run asynchronously after paint

2. System Requirements

Development Environment

Runtime Requirements

React has no server-side runtime requirements — it is a client-side library that runs in any ES2015-compatible JavaScript environment. For server rendering:

Note

The monorepo's package.json specifies "packageManager": "yarn@1.22.22". Using npm or pnpm to manage the monorepo workspace is not supported.

3. Configuration Reference

Feature Flags

React's behavior varies by release channel. Feature flags are defined in packages/shared/ReactFeatureFlags.js and overridden per-channel in packages/shared/forks/:

The scripts/flags/flags.js utility validates flag consistency across channels:

yarn flags

Build Environment Variables

React DevTools Environment Variables

Important

REACT_EDITOR (or fallback VISUAL / EDITOR) controls which editor React DevTools opens when you click a component's source location. Set it to your editor's CLI command (e.g., code, vim, webstorm).

React Compiler Configuration

The compiler accepts options via the Babel plugin configuration:

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      // EnvironmentConfig options
      // See compiler/packages/babel-plugin-react-compiler/src/HIR/Environment.ts
    }],
  ],
};

Key compiler options are validated via Zod schemas in Environment.ts. The compiler validates Rules of React at compile time:

ESLint Plugin Configuration

// eslint.config.js (flat config)
import reactHooks from 'eslint-plugin-react-hooks';

export default [
  {
    plugins: { 'react-hooks': reactHooks },
    rules: {
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
    },
  },
];

Note

eslint-plugin-react-hooks requires ESLint 7+ and supports up to ESLint 10 (GitHub #35758 tracks peerDependency updates for ESLint 10 support).

Scheduler Priority Levels

Defined in packages/scheduler/src/SchedulerPriorities.js:

The scheduler yields to the browser every frameYieldMs (5ms) to maintain responsive input handling.

4. Deployment & Scaling

Building React from Source

# Clone the repository
git clone https://github.com/facebook/react.git
cd react

# Install dependencies (must use Yarn)
yarn install

# Build all release channels
yarn build

# Build specific packages
node ./scripts/rollup/build.js react/index,react-dom/index --type=NODE_DEV

# Build for DevTools development
yarn build-for-devtools-dev

Tip

Use BUNDLES_FILTER to build only specific bundles during development: BUNDLES_FILTER=react-dom node ./scripts/rollup/build.js

Build Types

Release Channels

Publishing

Releases are automated via CI. Manual steps:

# Validate build output
yarn lint-build

# Run version checks
yarn version-check

# Download and verify an experimental build
yarn download-build

React Compiler Deployment

The compiler can be deployed as a Babel plugin in any build pipeline:

# Install
npm install babel-plugin-react-compiler react-compiler-runtime

# For React < 19, the runtime polyfill is required
npm install react-compiler-runtime

The react-compiler-runtime package provides the c() function (memo cache) as a polyfill for React versions below 19. React 19+ includes __COMPILER_RUNTIME natively.

Compiler Playground

The compiler includes a web-based playground at compiler/apps/playground/:

cd compiler
yarn install
yarn dev

Deployed automatically to Vercel on every push.

5. Operations

Running Tests

# Run all tests
yarn test

# Run tests for a specific release channel
yarn test-stable
yarn test-www

# Run tests for built artifacts
yarn test --build

# Run DevTools tests
yarn test-build-devtools

# Run DOM fixture tests
yarn test-dom-fixture

Note

Jest is not run directly — use yarn test which invokes scripts/jest/jest-cli.js. This script handles release channel selection, feature flag injection, and test environment setup.

Test Environment Variables

Type Checking

# Run Flow type checking
yarn flow

# Run Flow for CI (with inlined host configs)
yarn flow-ci

# Generate Flow configs for package-specific host configs
yarn postinstall

Tip

Flow configuration is auto-generated by scripts/flow/createFlowConfigs.js during postinstall. Each renderer gets its own .flowconfig with the correct host config inlined.

Linting

# Lint changed files
yarn linc

# Lint all files
yarn lint

# Format with Prettier
yarn prettier-all

# Check formatting
yarn prettier-check

Error Code Extraction

React uses numeric error codes in production to minimize bundle size. Error messages are mapped in scripts/error-codes/codes.json:

# Extract new error codes from source
yarn extract-errors

Changelog Generation

# Generate changelog between versions
yarn generate-changelog

The changelog generator (scripts/tasks/generate-changelog/) supports --codex and --claude flags for AI-assisted changelog writing, and --debug for verbose output.

Monitoring Build Health

# Validate built bundles for correctness
yarn lint-build

# Check module structure
node scripts/rollup/validate/index.js

6. Performance

Reconciler Performance Model

The Fiber reconciler uses a lanes model for priority scheduling:

• Each update is assigned a lane (bit in a 31-bit integer)
• Lanes represent priority levels (sync, default, transition, idle)
• The work loop processes one lane group at a time
• Higher-priority lanes can interrupt lower-priority work
• The shouldYieldToHost() check runs every 5ms to maintain UI responsiveness

Scheduler Implementation

The scheduler (packages/scheduler/src/) uses:

• Min-heap priority queue (SchedulerMinHeap.js): O(log n) insertion and extraction
• MessageChannel for yielding: avoids setTimeout minimum delay
• Task expiration: each priority level has a timeout; expired tasks are treated as synchronous
• Profiling support: optional event log buffer for the DevTools timeline

Bundle Size Optimization

Concurrent Features

7. Security

XSS Prevention

React auto-escapes all values embedded in JSX by default. This prevents cross-site scripting for the most common case:

// Safe — React escapes the value
<div>{userInput}</div>

// DANGEROUS — bypasses escaping
<div dangerouslySetInnerHTML={{ __html: userInput }} />

Caution

dangerouslySetInnerHTML bypasses React's XSS protection entirely. Only use it with sanitized HTML from a trusted source. Never pass user input directly.

URL Sanitization

React warns when a javascript: URL is passed to href or src attributes and blocks the navigation in development mode.

Supply Chain

• The repository is MIT-licensed
• Dependencies are pinned via yarn.lock and resolutions in package.json
• jsdom is pinned to 22.1.0 via resolutions to avoid upstream issues
• Internal packages use link: and workspace dependencies to avoid npm registry exposure

Server Components Security

• 'use server' functions are exposed as RPC endpoints — validate all inputs
• 'use client' marks the serialization boundary — props must be serializable
• Server Component output is a Flight protocol stream, not raw HTML — it goes through React's sanitization

8. Developer Internals

Repository Structure

facebook/react/
├── packages/                    # All npm-publishable packages
│   ├── react/                   # Core API (hooks, elements, components)
│   │   ├── src/                 # Source (27 files, 95K chars)
│   │   │   ├── ReactClient.js   # Client-side exports
│   │   │   ├── ReactServer.js   # Server Component exports
│   │   │   ├── ReactHooks.js    # Hook dispatch to reconciler
│   │   │   ├── ReactBaseClasses.js  # Component, PureComponent
│   │   │   ├── ReactElement.js  # createElement, JSX runtime
│   │   │   ├── ReactContext.js  # createContext
│   │   │   ├── ReactLazy.js     # lazy() implementation
│   │   │   ├── ReactMemo.js     # memo() implementation
│   │   │   └── ReactAct.js      # act() for testing
│   │   └── npm/                 # Build output structure
│   ├── react-dom/               # DOM renderer
│   │   ├── src/                 # DOM-specific code
│   │   ├── client.js            # createRoot, hydrateRoot
│   │   ├── server.js            # renderToPipeableStream, etc.
│   │   └── static.js            # prerender
│   ├── react-dom-bindings/      # DOM event system, property ops
│   │   └── src/
│   │       ├── client/          # DOM property operations
│   │       ├── events/          # Synthetic event system (23 files)
│   │       ├── server/          # Fizz instruction set
│   │       └── shared/          # Shared DOM utilities
│   ├── react-reconciler/        # Fiber reconciler (81 files, 1.6M chars)
│   │   └── src/
│   │       ├── ReactFiberBeginWork.js    # Render phase entry
│   │       ├── ReactFiberCommitWork.js   # Commit phase
│   │       ├── ReactFiberHooks.js        # Hook implementations
│   │       ├── ReactFiberReconciler.js   # Public reconciler API
│   │       ├── ReactChildFiber.js        # Child reconciliation
│   │       ├── ReactFiberWorkLoop.js     # Work loop scheduler integration
│   │       ├── ReactFiberLane.js         # Lane priority model
│   │       └── ReactFiberConfig.js       # Host config interface (shimmed per renderer)
│   ├── react-server/            # Flight server (37 files, 676K chars)
│   │   └── src/
│   │       └── flight/          # Server Component rendering
│   ├── react-client/            # Flight client (14 files, 256K chars)
│   │   └── src/                 # Stream deserialization
│   ├── scheduler/               # Cooperative scheduler
│   │   └── src/
│   │       ├── SchedulerMinHeap.js      # Min-heap priority queue
│   │       ├── SchedulerPriorities.js   # 5 priority levels
│   │       └── SchedulerProfiling.js    # Timeline profiling
│   ├── shared/                  # Shared utilities (35 files, 98K chars)
│   │   ├── ReactFeatureFlags.js         # Feature flag defaults
│   │   ├── ReactSymbols.js              # Element type symbols
│   │   ├── ReactTypes.js                # Flow type definitions
│   │   ├── ReactVersion.js              # Version string
│   │   └── forks/                       # Per-channel flag overrides
│   ├── react-devtools-shared/   # DevTools core (20 files, 160K chars)
│   └── ...                      # Other packages
├── compiler/                    # React Compiler
│   ├── packages/
│   │   ├── babel-plugin-react-compiler/  # Main compiler plugin
│   │   │   └── src/
│   │   │       ├── Babel/               # Babel integration
│   │   │       ├── Entrypoint/          # Plugin options, pipeline entry
│   │   │       ├── HIR/                 # High-level IR (control flow graph)
│   │   │       ├── SSA/                 # Static single assignment
│   │   │       ├── Optimization/        # Constant propagation, DCE
│   │   │       ├── Inference/           # Mutation/aliasing analysis
│   │   │       ├── TypeInference/       # Type inference
│   │   │       ├── ReactiveScopes/      # Memoization scope construction
│   │   │       ├── Validation/          # Rules of React validation
│   │   │       ├── Transform/           # AST transforms
│   │   │       ├── Flood/               # Data flow analysis
│   │   │       └── Utils/               # Shared utilities
│   │   ├── eslint-plugin-react-compiler/
│   │   ├── react-compiler-runtime/
│   │   ├── react-compiler-healthcheck/
│   │   ├── react-mcp-server/            # MCP integration
│   │   ├── react-forgive/               # Fault-tolerant mode
│   │   ├── snap/                        # Snapshot testing
│   │   └── make-read-only-util/
│   └── apps/
│       └── playground/                  # Compiler playground (Next.js)
├── fixtures/                    # Integration test apps
│   ├── flight/                  # Server Components demo
│   ├── fizz/                    # Streaming SSR demo
│   ├── ssr/                     # Classic SSR demo
│   ├── dom/                     # DOM behavior fixtures
│   ├── devtools/                # DevTools regression fixtures
│   └── ...
├── scripts/                     # Build, test, CI tooling
│   ├── rollup/                  # Build configuration (11 files, 133K chars)
│   │   ├── build.js             # Main build orchestrator
│   │   ├── bundles.js           # Bundle definitions
│   │   ├── wrappers.js          # Module wrapper generation
│   │   └── plugins/             # Custom Rollup plugins
│   ├── jest/                    # Test configuration (25 files, 57K chars)
│   ├── flow/                    # Flow configuration generation
│   ├── babel/                   # Custom Babel transforms
│   ├── error-codes/             # Error code extraction
│   ├── ci/                      # CI scripts
│   ├── flags/                   # Feature flag management
│   ├── eslint-rules/            # Custom ESLint rules
│   └── shared/                  # Shared script utilities
└── flow-typed/                  # Flow type definitions for dependencies

Architecture Deep Dive: Fiber Reconciler

The reconciler (packages/react-reconciler/src/, 81 files, 1.6M source chars) is the heart of React. Key files:

ReactFiberWorkLoop.js — The main work loop. Coordinates scheduling, render phase, commit phase, and error recovery. Contains performConcurrentWorkOnRoot, performSyncWorkOnRoot, and the yield-to-host logic.

ReactFiberBeginWork.js — Render phase processing. For each fiber, determines what changed and constructs the work-in-progress tree. Handles all component types: function components, class components, host elements, portals, Suspense boundaries, fragments, profiler, and more.

ReactFiberHooks.js — All hook implementations. Maintains a linked list of hooks per fiber. The dispatcher pattern switches between mount, update, and re-render hook implementations. Key hooks: useState, useReducer, useEffect, useLayoutEffect, useRef, useMemo, useCallback, useContext, useTransition, useDeferredValue, useId, useSyncExternalStore, useActionState, useOptimistic.

ReactFiberCommitWork.js — Commit phase. Three sub-phases:

1. Before mutation — getSnapshotBeforeUpdate, ref detachment
2. Mutation — DOM insertions, updates, deletions
3. Layout — useLayoutEffect, ref attachment, componentDidMount/DidUpdate

ReactChildFiber.js — Child reconciliation algorithm. Implements the key-based diffing for lists, including the optimization for the common case of appending to the end.

ReactFiberLane.js — The lanes priority model. Each lane is a bit in a 31-bit integer. Lanes enable fine-grained priority control:

ReactFiberConfig.js — Host config interface. Each renderer provides its own implementation (DOM, Native, Noop, Art, Test). The module is shimmed at build time via Rollup's module replacement.

Architecture Deep Dive: React Compiler

The compiler (compiler/packages/babel-plugin-react-compiler/src/) is a 7-phase pipeline that transforms React components into memoized equivalents:

Phase 1 — HIR Construction: HIR/BuildHIR.ts converts Babel AST into a High-level Intermediate Representation (control flow graph). Then SSA/EnterSSA.ts converts to Static Single Assignment form, and SSA/EliminateRedundantPhi.ts removes unnecessary phi nodes.

Phase 2 — Optimization: Optimization/ConstantPropagation.ts performs sparse conditional constant propagation. Optimization/DeadCodeElimination.ts removes unreferenced instructions.

Phase 3 — Type & Effect Inference: TypeInference/InferTypes.ts runs constraint-based type unification. Inference/AnalyseFunctions.ts analyzes nested function effects. Inference/InferMutationAliasingEffects.ts uses abstract interpretation to infer which values are mutated or aliased.

Phase 4 — Reactive Scope Construction: Groups co-mutating variables into reactive scopes that will become useMemo calls. Aligns scopes to block boundaries, merges overlapping scopes, and computes minimal dependencies.

Phase 5 — HIR to Reactive Function: ReactiveScopes/BuildReactiveFunction.ts converts the CFG into a tree structure.

Phase 6 — Reactive Function Optimization: Prunes non-escaping scopes, unused scopes, and non-reactive dependencies. Merges scopes that invalidate together.

Phase 7 — Code Generation: ReactiveScopes/CodegenReactiveFunction.ts generates the final Babel AST with memoization code.

Architecture Deep Dive: Flight Protocol (Server Components)

The Flight protocol enables streaming Server Components from server to client:

Server side (packages/react-server/src/): Renders the Server Component tree, serializing it as a custom streaming format. Components can be async. Client Components are serialized as references (module ID + export name). Props are serialized as JSON with support for special types (Date, Map, Set, FormData, typed arrays).

Client side (packages/react-client/src/): Deserializes the stream, resolving Client Component references using the bundler integration. Reconstructs the React element tree and passes it to the client renderer.

Bundler integrations provide the module reference system:

Module Reference: Core Exports

packages/react/src/ReactClient.js exports:

Code Patterns and Conventions

__DEV__ guards: All development-only code (warnings, validation, stack traces) is wrapped in if (__DEV__) { ... }. The build system replaces __DEV__ with true (development) or false (production), and dead code elimination removes the branches.

Feature flags: Runtime behavior variations use flags from packages/shared/ReactFeatureFlags.js. Flags are boolean constants that the build system may inline.

Fork pattern: Platform-specific code uses forks/ directories. The Rollup build replaces module imports with the correct fork based on the target renderer. Example: ReactFiberConfig.js is replaced with ReactFiberConfigDOM.js for react-dom.

Error codes: Production error messages are replaced with numeric codes. The mapping is in scripts/error-codes/codes.json. Development builds include the full message; production builds include a URL to look up the error.

Flow types: Core packages use Flow for type checking. Type annotations use Flow syntax (type Foo = { ... }, function bar(x: string): void). The compiler packages use TypeScript instead.

Shared internals: Cross-package communication uses __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE (React) and __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE (ReactDOM). These are private APIs not intended for external use.

Testing Strategy

Custom Jest environment files:

• ReactDOMServerIntegrationEnvironment.js — Extends Node environment for SSR integration tests
• ReactJSDOMEnvironment.js — Extends JSDOM environment with custom teardown

Custom Jest matchers and reporters:

• scripts/jest/matchers/ — Custom assertion helpers
• scripts/jest/spec-equivalence-reporter/ — Reports spec equivalence across configurations
• scripts/jest/sizeBalancedSequencer.js — Distributes tests across workers by size

Potential Improvements

Based on the codebase analysis, the following areas have room for improvement:

• react-reconciler/src/ size: At 81 files and 1.6M chars, the reconciler is exceptionally large. Some files (e.g., ReactFiberBeginWork.js, ReactFiberHooks.js, ReactFiberCommitWork.js) are individually massive. Breaking these into smaller, focused modules would improve maintainability.

• Flow to TypeScript migration: Core packages still use Flow while the compiler uses TypeScript. A full migration would unify the type system and improve IDE support.

• Test infrastructure complexity: The test setup involves custom Jest configs, environments, sequencers, and preprocessors across 25 files. This makes it difficult for new contributors to understand how to run and write tests.

• DevTools bundle: react-devtools-shared alone is 20 files / 160K chars of source. The DevTools architecture could benefit from clearer separation between the fiber inspection backend and the UI frontend.

Contributing Guide

1. Fork the repository and clone locally
2. Install dependencies: yarn install
3. Create a branch from main
4. Make changes following existing code patterns
5. Run tests: yarn test
6. Run type checks: yarn flow
7. Run linting: yarn lint
8. Format code: yarn prettier-all
9. Submit a pull request

Note

The repository uses Yarn 1.22.22 workspaces. Do not use npm or pnpm. The postinstall script generates Flow configs — run yarn install after any dependency changes.

Custom ESLint rules (scripts/eslint-rules/):

• no-production-logging — Prevents console.* calls outside __DEV__ guards
• no-for-of-loops — Bans for...of to avoid iterator overhead
• warning-args — Validates warning/error function call signatures
• safe-string-coercion — Prevents implicit string coercion of symbols/temporals

9. Integration Points

Bundler Integration

React provides different builds for different bundlers and environments:

Custom Renderers

Build a custom renderer by implementing the host config interface and connecting it to the reconciler:

import Reconciler from 'react-reconciler';

const hostConfig = {
  createInstance(type, props) { /* ... */ },
  appendInitialChild(parent, child) { /* ... */ },
  appendChild(parent, child) { /* ... */ },
  removeChild(parent, child) { /* ... */ },
  commitUpdate(instance, type, oldProps, newProps) { /* ... */ },
  // ... ~60 methods total
};

const MyRenderer = Reconciler(hostConfig);

The react-noop-renderer (packages/react-noop-renderer/) serves as a reference implementation for custom renderers.

DevTools Integration

React DevTools communicates via a Bridge class (packages/react-devtools-shared/src/bridge.js) that abstracts the transport layer (WebSocket for standalone, window.postMessage for extensions).

The backend hooks into React's internal fiber tree via the __REACT_DEVTOOLS_GLOBAL_HOOK__ global that the extension injects before React loads.