react-learner

简体中文 | English

A minimal React + TypeScript + Vite playground wired up so that your app imports React directly from the React source tree, with full source maps and breakpoints. It's designed for one thing: stepping through React's internals (react, react-dom, react-reconciler, scheduler, shared, …) while running a real app, instead of debugging the bundled / minified react.production.min.js.

How it works

Vite is configured to:

1. Alias every React-related package name (react, react-dom, react-reconciler, react-client, scheduler, shared, react/jsx-runtime, react/jsx-dev-runtime, …) to your local clone of the React repository.
2. Resolve a few "fork" entry points that React's build step normally resolves (e.g. ReactFiberConfig → ReactFiberConfig.dom.js, ReactFlightClientConfig → its DOM fork, the shared/*Internals client/server forks).
3. Strip Flow type annotations on the fly from any .js file under your React source path, since the source tree is written in Flow.
4. Inject the build-time globals React expects (__DEV__, __PROFILE__, __EXPERIMENTAL__, __VARIANT__).

The result: import { useState } from 'react' actually pulls react/src/ReactHooks.js from disk. Set a breakpoint in your editor or in DevTools, and you're inside React.

Prerequisites

• Node.js 18+ and Yarn (this repo uses Yarn 1.22 with PnP — see package.json).
• A local clone of the React repository somewhere on disk. You only need the source — you do not need to run React's own build.

Getting started

# 1. Clone this repo
git clone <this-repo-url> react-learner
cd react-learner

# 2. Clone React somewhere convenient (skip if you already have it)
git clone https://github.com/facebook/react.git ../react

# 3. Tell react-learner where React's source lives
cp .env.example .env
# then open .env and set REACT_SRC_PATH to the absolute path of
# <your-react-clone>/packages

# 4. Install deps and start the dev server
yarn install
yarn dev

Open the URL Vite prints (typically http://localhost:5173). Edits to files under REACT_SRC_PATH hot-reload just like edits to your own src/.

Configuring the React source path

vite.config.ts reads the path from a .env file in the project root via Vite's loadEnv. The only required variable is:

# Absolute path is recommended
REACT_SRC_PATH=/absolute/path/to/react/packages

# Relative paths (resolved against the project root) also work:
# REACT_SRC_PATH=../react/packages

If REACT_SRC_PATH is missing, Vite will fail fast with a clear error message at startup. .env is git-ignored; commit only .env.example.

Suggested debugging workflow

1. Start yarn dev.
2. Open the running page in Chrome and open DevTools → Sources.
3. Source files under your React clone show up under their real paths (e.g. …/react/packages/react-reconciler/src/ReactFiberWorkLoop.js). Set breakpoints there.
4. Trigger the relevant code path in src/App.tsx (or anywhere under src/). You'll land inside React with a readable call stack.

If you'd rather edit React itself (e.g. add console.logs), just edit the file in your React clone — Vite will pick up the change and HMR.

Project layout

react-learner/
├─ src/                 # Your playground app — edit freely
├─ vite.config.ts       # The interesting part: aliases + Flow stripping
├─ .env.example         # Copy to .env and fill in REACT_SRC_PATH
├─ index.html
└─ package.json

Scripts

• yarn dev — start the Vite dev server with React-source debugging wired up
• yarn build — type-check and produce a production build (still using your local React source)
• yarn preview — preview the production build
• yarn lint — run ESLint

Caveats

• optimizeDeps is disabled. Dep pre-bundling would defeat the whole point of debugging from source.
• The Flow-stripping plugin only runs on .js files inside REACT_SRC_PATH. Your own app code stays untouched.
• The default flags treat the build as a development, experimental, non-profiling, non-variant build (__DEV__: true, __EXPERIMENTAL__: true, __PROFILE__: false, __VARIANT__: false). If you want to debug a different build, edit the define block in vite.config.ts.
• Tested against recent main-branch React. Older release branches may need extra aliases as React's internal layout changes over time.

License

MIT.