Onboarding: facebook/react

Generated by RepoPilot · 2026-05-04 · Source

Verdict

GO — Healthy across the board

• Last commit 2d ago
• 5 active contributors
• Distributed ownership (top contributor 31%)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

This is the official facebook/react monorepo containing the React UI library runtime, the experimental React Compiler (babel-plugin-react-compiler), React DevTools, React Native renderer, and a compiler playground app. It solves the problem of building declarative, component-based UIs for web and native platforms, with the compiler sub-project automatically memoizing components to eliminate manual useMemo/useCallback calls. Large Yarn-workspace monorepo: packages/ holds all publishable packages (react, react-dom, react-reconciler, babel-plugin-react-compiler, react-compiler-runtime, etc.), fixtures/ has integration test apps, apps/playground is a Next.js 15 app serving the live compiler playground, and scripts/ contains build/release tooling. The .claude/ directory contains AI-assisted skill scripts for feature flags, flow types, test generation, and error extraction.

Who it's for

React core team contributors and advanced open-source contributors who want to fix bugs in the React reconciler, implement new features like Server Components or concurrent rendering primitives, or develop the React Compiler. Also used by library authors who need to understand React internals.

Maturity & risk

Extremely mature — React is ~10 years old, has tens of millions of weekly npm downloads, and is one of the most starred JavaScript repos on GitHub. CI is thorough: .github/workflows includes runtime_build_and_test.yml, runtime_fuzz_tests.yml, compiler_typescript.yml, and devtools_regression_tests.yml. Commits are recent and frequent, making this definitively production-ready.

Very low risk for consuming the published packages (react, react-dom), but contributing to internals is high-complexity — the reconciler and concurrent mode code are intricate. The monorepo uses Yarn workspaces with many interdependent packages; mismatched workspace versions can cause subtle breakage. The React Compiler (packages/babel-plugin-react-compiler) is still experimental and its API surface is not yet stable.

Active areas of work

Active development on the React Compiler (babel-plugin-react-compiler) with nightly prereleases via .github/workflows/compiler_prereleases_nightly.yml. The compiler playground at apps/playground is actively maintained with Playwright e2e tests. Runtime prereleases are also automated. The .github/workflows/runtime_fuzz_tests.yml suggests active work on correctness guarantees for concurrent features.

Get running

git clone https://github.com/facebook/react.git cd react corepack enable yarn install --frozen-lockfile

To run the compiler playground locally:

cd apps/playground yarn dev

To build all packages:

yarn build

Daily commands:

Full monorepo install:

yarn install --frozen-lockfile

Compiler playground dev server (Next.js on localhost:3000):

cd apps/playground && yarn dev

Build runtime packages:

yarn build

Run runtime tests:

yarn test

Run playground e2e tests:

cd apps/playground && yarn test

Map of the codebase

• README.md — Top-level entry point explaining React's purpose, contribution guidelines, and links to documentation — required reading before any contribution.
• CONTRIBUTING.md — Defines the contribution workflow, coding standards, and PR process for the entire React repository.
• compiler/CLAUDE.md — AI-assistant instructions that encode the compiler sub-project's conventions, key files, and development patterns.
• compiler/apps/playground/app/page.tsx — Root Next.js page for the React Compiler playground — the main UI entry point that wires together the compiler and editor components.
• compiler/apps/playground/components/Editor/ConfigEditor.tsx — Core editor component for configuring the React Compiler in the playground — central to understanding how compiler options are exposed to users.
• .github/workflows/runtime_build_and_test.yml — CI definition for the runtime — defines how React itself is built and tested, critical for understanding the build pipeline.
• babel.config.js — Root Babel configuration that governs how all JavaScript/TypeScript source across the monorepo is transpiled during build and test.

Components & responsibilities

• babel-plugin-react-compiler — undefined

How to make changes

Add a new compiler configuration option to the playground

1. Define the new option's type and default value in the compiler config schema. (compiler/apps/playground/components/Editor/ConfigEditor.tsx)
2. Add UI controls (checkbox, dropdown, or input) for the new option in the ConfigEditor component. (compiler/apps/playground/components/Editor/ConfigEditor.tsx)
3. Wire the new option into the playground page so it is passed to the compiler transform. (compiler/apps/playground/app/page.tsx)
4. Add a snapshot test capturing the expected compiler output when the new option is enabled. (compiler/apps/playground/__tests__/e2e/page.spec.ts)

Add a new E2E playground test scenario

1. Write the new Playwright test case in the E2E spec file, navigating to the playground and asserting on compiler output. (compiler/apps/playground/__tests__/e2e/page.spec.ts)
2. Generate or update the corresponding snapshot file with the expected output text for the new scenario. (compiler/apps/playground/__tests__/e2e/__snapshots__/page.spec.ts)

Add a new GitHub Actions CI workflow

1. Create the new workflow YAML file following the naming convention (runtime_, compiler_, or shared_*) in the workflows directory. (.github/workflows/runtime_build_and_test.yml)
2. Reference any shared lint or check jobs by reusing the existing shared workflow patterns. (.github/workflows/shared_lint.yml)

Bump React package versions across the monorepo

1. Update the canonical version constants in the central versions file. (ReactVersions.js)
2. Update the CHANGELOG with the new version's release notes. (CHANGELOG.md)
3. Trigger the pre-release workflow to publish the new versions to npm. (.github/workflows/runtime_prereleases.yml)

Why these technologies

• Next.js (App Router) — Provides file-based routing, server components, and fast local development for the playground web app without requiring a custom server setup.
• Babel — React's compiler is implemented as a Babel plugin, making it easy to integrate into existing JavaScript toolchains and test transforms on arbitrary source code.
• Playwright — Used for E2E testing of the playground because it can drive a real browser, capture rendered compiler output, and compare against snapshots reliably.
• TypeScript — The compiler sub-project is written in TypeScript for type safety during complex AST manipulation, reducing bugs in the transformation logic.
• Yarn Workspaces (monorepo) — Manages multiple interdependent packages (react, react-dom, compiler plugin, playground) in a single repository with shared dependencies and linked local packages.

Trade-offs already made

• In-browser compilation in the playground

  • Why: Eliminates server round-trips, making the playground feel instant and allowing offline use.
  • Consequence: The full compiler bundle (including Babel) must be shipped to the browser, increasing initial load size.

• Separate babel.config files for different build modes

  • Why: Allows the compiler transform to be opt-in (babel.config-react-compiler.js) without affecting normal builds.
  • Consequence: Developers must be aware of which config is active, adding cognitive overhead to the build system.

• Snapshot-based E2E tests for compiler output

  • Why: Provides high-confidence regression detection for compiler output changes with minimal test maintenance.
  • Consequence: Snapshots must be manually updated on intentional output changes, which can cause false-positive failures.

• Monorepo with Yarn Workspaces

  • Why: Co-locating the compiler, runtime, and playground enables atomic changes across package boundaries.
  • Consequence: Increased complexity in CI configuration and local setup; contributors must understand workspace linking.

Non-goals (don't propose these)

• The playground is not intended to be a production code editor — it is a demonstration and debugging tool only.
• The React Compiler does not aim to replace manual useMemo/useCallback annotations — it supplements them.
• The repository does not include a backend API service — all playground compilation runs client-side.
• The compiler does not guarantee 100% compatibility with all JavaScript patterns — it bails out on unsupported syntax.

Traps & gotchas

1. Node version matters — the repo expects a specific Node LTS; mismatches cause cryptic Yarn workspace errors. 2) The playground's postinstall script runs ./scripts/link-compiler.sh which symlinks local compiler packages — if you haven't built the compiler first (yarn workspace babel-plugin-react-compiler run build), the playground will fail to start. 3) Flow types are used in runtime packages but NOT checked in standard CI — you need to run flow check separately and install the correct Flow binary version pinned in .flowconfig. 4) The apps/playground/package.json preinstall runs yarn install --frozen-lockfile from the repo root, so running yarn install inside apps/playground alone will re-run root install.

Architecture

Concepts to learn

• Fiber Reconciler — React's entire rendering engine is the Fiber architecture in packages/react-reconciler — understanding fibers (units of work with priority and interruptibility) is mandatory for any runtime contribution.
• Concurrent Mode / Time Slicing — React 18+'s scheduler can pause and resume rendering work across frames; the ReactFiberWorkLoop.js implements this via lanes — a bitmask priority system.
• Automatic Memoization via Compiler IR — The React Compiler (babel-plugin-react-compiler) builds an intermediate representation of component code to infer which values are stable and insert React.memo/useMemo calls — understanding compiler IRs is key to contributing.
• React Server Components (RSC) — A rendering model where components run only on the server and stream serialized UI to the client — implemented across packages/react-server and packages/react-client in this repo.
• Lane-based Priority Scheduling — React 18 replaced the legacy expiration-time model with a bitmask 'lanes' system to represent multiple concurrent update priorities — central to how useTransition and Suspense work.
• Babel Plugin AST Transform — The compiler is delivered as a Babel plugin that transforms JSX/JS ASTs at build time — contributors need to understand Babel visitor patterns and @babel/types to work on packages/babel-plugin-react-compiler.
• Algebraic Effects (conceptual basis for Hooks) — React Hooks are conceptually inspired by algebraic effects — understanding this explains why hooks can only be called at the top level and how the dispatcher pattern in ReactCurrentDispatcher.js works.

Related repos

• preactjs/preact — 3KB alternative to React with the same component API — direct competitor in the same ecosystem.
• solidjs/solid — Fine-grained reactivity alternative to React's VDOM reconciler approach, often compared architecturally.
• facebook/react-native — Companion repo that uses the React reconciler from this repo to render to native iOS/Android views.
• vercel/next.js — The most widely used React framework, built on top of this repo's packages — understanding react internals is essential for Next.js contributors.
• reactwg/react-18 — Working group repo that documented the design decisions behind concurrent features implemented in this repo.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Playwright E2E tests for React Compiler Playground error states and edge cases

The compiler playground at compiler/apps/playground already has Playwright configured (test script with --workers=4) and a test suite, but compiler error states (invalid syntax, unsupported patterns, bailout messages) are likely undertested. Since the playground is a primary way developers interact with the React Compiler, ensuring error boundaries, diagnostic messages, and URL-based state sharing (via lz-string) work correctly is high value for new contributors to the compiler ecosystem.

• [ ] Examine existing tests in compiler/apps/playground/tests/ to identify gaps around error handling and diagnostic display
• [ ] Add a Playwright test that inputs a component with a known compiler bailout (e.g., a component using a ref in a way that violates Rules of React) and asserts the correct diagnostic message is shown in the output panel
• [ ] Add a test that verifies lz-string URL sharing round-trips correctly: encode a snippet, load the URL, and assert the editor content matches
• [ ] Add a test for invalid/unparseable JavaScript input and assert the playground shows a parser error rather than crashing silently
• [ ] Run yarn test inside compiler/apps/playground to verify all new tests pass with --workers=4

Add a GitHub Actions workflow for Compiler Playground build verification on PRs

Inspecting .github/workflows/, there are workflows for compiler TypeScript checks (compiler_typescript.yml), prereleases, and runtime build/test, but no dedicated CI workflow that builds the Next.js playground app (compiler/apps/playground) and runs its Playwright tests on every PR. The playground has a vercel-build script and a full Playwright test suite, but these are only run on Vercel deployments, meaning regressions in the playground UI can land undetected in the main repo CI.

• [ ] Create .github/workflows/compiler_playground_ci.yml that triggers on pull_request for paths: compiler/**
• [ ] Add a job that sets up Node.js (using .nvmrc), runs yarn install --frozen-lockfile from the repo root, then cd compiler/apps/playground && yarn build to catch Next.js build failures
• [ ] Add a second job (or step) that installs Playwright browsers via npx playwright install --with-deps and runs yarn test inside compiler/apps/playground
• [ ] Cache node_modules and the Next.js .next/cache using actions/cache keyed on yarn.lock hash to keep CI fast
• [ ] Verify the workflow runs correctly on a draft PR that touches a file under compiler/apps/playground/

Add unit tests for the React Compiler's LRU cache usage in the playground API layer

The playground package.json lists lru-cache ^11.2.2 as a dependency, which is used to memoize compilation results server-side (to avoid re-compiling identical inputs). This caching logic is a performance-critical path with no obvious dedicated unit tests. A cache eviction bug or key collision could cause stale compilation output to be served. Adding focused unit tests for cache hit/miss/eviction behavior—independently of the full Playwright suite—gives fast feedback and documents the intended caching contract.

• [ ] Locate the file(s) in compiler/apps/playground that instantiate and use lru-cache (likely in a lib/, api/, or utils/ directory under the app)
• [ ] Extract or confirm the cache key construction logic (likely a hash of source code + compiler options) into a pure, testable function if it isn't already
• [ ] Add a Jest or Vitest unit test file (e.g. tests/compileCache.test.ts) that covers: cache miss triggers compilation, cache hit returns cached result without re-compiling, cache eviction when capacity (maxSize) is exceeded causes re-compilation on next call
• [ ] Add a test asserting that two inputs differing only in compiler options (e.g. different feature flags from the playground config) produce distinct cache entries
• [ ] Wire the new test file into the playground's test script or add a separate 'test

Good first issues

1. Add missing Playwright e2e tests in apps/playground/tests/ for the URL share-link feature (lz-string encoding/decoding of editor state) — currently not covered. 2) Several .claude/skills/ SKILL.md files (e.g., extract-errors, fix, verify) exist as AI prompt templates but lack example inputs/outputs — adding concrete examples would help contributors use them correctly. 3) The apps/playground README is minimal; a new contributor could document the Monaco Editor integration architecture and how in-browser Babel compilation is wired up in apps/playground/src/.

Top contributors

• @eps1lon — 18 commits
• @josephsavona — 18 commits
• @hoxyq — 9 commits
• @jackpope — 7 commits
• @rubennorte — 6 commits

Recent commits

• 9635257 — [DevTools] Preserve -Infinity in inspected values (#36347) (zxuhan)
• 4f273bd — fix(devtools): clear highlight when mouse leaves DevTools panel (#36177) (petertdinh)
• f4e0d4e — [enableInfiniteRenderLoopDetection] Add a flag to force throwing (#36357) (hoxyq)
• ad5dfc8 — Add react-flight-server-fb package for Meta's internal bundler (#36309) (imdreamrunner)
• 561ed52 — Fix formatting (#36332) (eps1lon)
• 142cfde — Fix FragmentInstance listener leak: normalize boolean vs object capture options per DOM spec (#36047) (Dhakshin2007)
• 94643c3 — Suggest correct casing for misspelled credentialless iframe attribute (#36322) (vmx906)
• 306a01b — Add credentialless as a recognized boolean attribute for iframes (#36148) (vmx906)
• 3ee1fe4 — Fix contributor attribution for ESLint v10 support (jackpope)
• 1ddff43 — Add null check before calling fabricSuspendOnActiveViewTransition (#36310) (zeyap)

Security observations

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.