A Appendix

Appendix A · React Source Code File Organization

The four bundles below draw a clean boundary between what React is and where it runs. Every function discussed in this course lives in one of these files; the diagram shows the full call-flow across them, and the table maps each architectural concern to its home.

A.1 · Call-flow across packages

┌─────────────────────────────────────────────────────────────────────────────┐
│                          USER ACTIONS                                       │
│   setState / useReducer    startTransition    flushSync    User Events      │
└──────────────┬─────────────────┬────────────────┬──────────────┬────────────┘
               ▼                 ▼                ▼              ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         LANE ASSIGNMENT                                     │
│     requestUpdateLane       requestTransitionLane    requestDeferredLane    │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                   UPDATE CREATION & QUEUEING                                │
│   dispatchSetState   dispatchReducerAction                                  │
│   enqueueConcurrentHookUpdate   markRootUpdated                             │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        SCHEDULING ENTRY                                     │
│          scheduleUpdateOnFiber   ──▶   ensureRootIsScheduled                │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         LANE SELECTION                                      │
│    getNextLanes  ──▶  lanesToEventPriority  ──▶  lanesToSchedulerPriority  │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      SCHEDULER INTEGRATION                                  │
│  scheduleCallback ▶ requestHostCallback ▶ schedulePerformWorkUntilDeadline  │
│  performWorkUntilDeadline ▶ workLoop ──▶ shouldYield (time-slice check)     │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         RENDER ENTRY                                        │
│  performConcurrentWorkOnRoot  /  performSyncWorkOnRoot                      │
│                 └──▶ prepareFreshStack                                      │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          RENDER LOOP                                        │
│  renderRootConcurrent ──▶ workLoopConcurrent  (checks shouldYield)         │
│  renderRootSync       ──▶ workLoopSync                                      │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        FIBER PROCESSING                                     │
│      performUnitOfWork ──▶ beginWork ──▶ completeUnitOfWork ──▶ completeWork│
│                                │                    │                       │
│                         LANE FILTERING        (bubbles flags)               │
│             isSubsetOfLanes / includesLane / includesSomeLane               │
│                       mergeLanes / removeLanes                              │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     COMPONENT RENDERING                                     │
│    updateFunctionComponent ──▶ renderWithHooks ──▶ reconcileChildren        │
│                                      │                                      │
│                               HOOK PROCESSING                               │
│      mountState / updateState    mountEffect / updateEffect                 │
│      updateReducer / updateReducerImpl                                      │
└──────────────┬──────────────────────────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          COMMIT PHASE                                       │
│  commitRoot                                                                 │
│    ├─▶ commitBeforeMutationEffects                                          │
│    ├─▶ commitMutationEffects                                                │
│    ├─▶ commitLayoutEffects                                                  │
│    └─▶ commitPassiveEffects ──▶ flushPassiveEffects                        │
│              ├─▶ commitPassiveMountEffects ──▶ commitHookEffectListMount    │
│              └─▶ commitPassiveUnmountEffects ──▶ commitHookEffectListUnmount│
└─────────────────────────────────────────────────────────────────────────────┘
                     │
                     └──▶  ensureRootIsScheduled  (loop continues)

Key flow paths:

• Update flow: User action → lane assignment → update creation → scheduling → render
• Render flow: Scheduler → render entry → render loop → fiber processing → component rendering
• Hook flow: Component rendering → hook processing → lane filtering → state update
• Commit flow: Render complete → commit phases → effect processing
• Loop flow: Commit complete → scheduling → next render

A.2 · Package responsibilities

react.js — Core API Layer (platform-agnostic)

Provides stable public APIs that work across all platforms. Contains no platform-specific code — no DOM, no iOS, no Android.

• Component APIs: React.Component, React.PureComponent
• JSX transformation: React.createElement, React.cloneElement
• Context API: React.createContext
• Hook interfaces (dispatcher pattern): useState, useEffect, useReducer, …
• Refs: React.createRef, React.forwardRef
• Fragments: React.Fragment
• Scheduler: task prioritization (decides when to work)
• Dispatcher registry: ReactCurrentDispatcher (pointer to implementation)

What it actually does

// Public API — just delegates to the renderer
function useState(initialState) {
  var dispatcher = resolveDispatcher();
  return dispatcher.useState(initialState); // calls into react-dom
}

// JSX → React elements
React.createElement('div', { className: 'app' }, 'Hello');

react-dom.js — DOM Renderer (browser-specific)

Implements React for web browsers. Manipulates the real DOM. Contains the actual logic behind every hook.

• Hook implementations: mountState, updateState, mountEffect, updateEffect
• Reconciliation: reconcileChildren, reconcileChildFibers (diffing algorithm)
• Render phase: beginWork, completeWork (build fiber tree)
• Commit phase: commitWork, commitMutationEffects (apply DOM changes)
• DOM operations: createElement, appendChild, removeChild
• Event system: synthetic events, event delegation
• Hydration: SSR client-side takeover
• Entry points: createRoot, hydrateRoot, render (legacy)

What it actually does

// Actual hook implementation
function mountState(initialState) {
  var hook = mountWorkInProgressHook();
  hook.memoizedState = hook.baseState = initialState;
  // ... fiber node logic
  return [hook.memoizedState, dispatch];
}

// Reconciliation (diffing)
function reconcileChildren(current, workInProgress, nextChildren) {
  // Compare old vs new, create fiber nodes
}

// Commit changes to real DOM
function commitWork(finishedWork) {
  const domElement = document.createElement('div');
  parent.appendChild(domElement);
}

Complete end-to-end flow

// 1. Your code (uses react.js public API)
import React, { useState } from 'react';
import { createRoot } from 'react-dom/client';

function App() {
  const [count, setCount] = useState(0); // ← react.js wrapper
  return <div>{count}</div>;            // ← react.js createElement
}

// 2. Entry point (react-dom.js)
const root = createRoot(document.getElementById('root'));
root.render(<App />);

// 3. Render starts — react-dom.js sets the dispatcher
ReactCurrentDispatcher.current = HooksDispatcherOnMountInDEV;

// 4. Hook execution
//   useState(0)
//     → react.js:    dispatcher.useState(0)
//     → react-dom.js: mountState(0)   ← actual implementation

// 5. Reconciliation (react-dom.js)
//   reconcileChildren() → build fiber tree, find diffs

// 6. Commit (react-dom.js)
//   commitWork() → update real DOM

A.3 · react.js vs react-dom.js at a glance

A.4 · One API, multiple renderers

The reason react.js and react-dom.js are separate is that the same public API can be backed by completely different renderers:

// Same react.js import for all platforms:
import React, { useState } from 'react';

// Different renderers:
import { createRoot } from 'react-dom/client';  // Web
import { AppRegistry } from 'react-native';     // Mobile
import { render } from 'react-three-fiber';     // 3D
import { render } from 'ink';                   // Terminal CLI

All use the same useState API from react.js, but each renderer supplies its own implementation. react.js = "what to do" (API + Scheduler); react-dom.js = "how to do it for the web" (implementation + DOM).

Appendix B · Additional Code References

Key external resources referenced in this course and useful starting points for exploring the live source.

Appendix C · Glossary

Quick reference for React internals terminology used throughout the course.

Core concepts

Render cycle

Double buffering

Lanes & scheduling

Suspense & Activity

Hooks & state internals

Effects

Server-side React

Fiber properties reference

Common Fiber tags