Bootstrap - Packages, JSX and the Dispatcher

The package split, and why it is shaped this way

The first surprise is that the code you import from is not the code that does the work.

react-dom's package.json lists only scheduler as a dependency and react as a peer dependency.¹ The reconciler is not a runtime dependency. It is inlined into the react-dom bundle at build time. The Rollup bundle for react-dom/client keeps react and react-dom external², and the build marks all dependencies and peerDependencies of a package as external too.³ So react-dom-client.production.js contains a full private copy of the reconciler. react-native and react-three-fiber (via the public react-reconciler npm package) each ship their own copy.

Why split it like this?

• One component model, many renderers. A component written against react runs under DOM, Native, ART or a custom renderer. Only the host config changes.
• Libraries depend only on react. A component library should not pin react-dom, so react has to be importable with no renderer present.
• A single source of truth for "who is rendering right now". That is the shared internals object below.

The JSX transform

Since React 17 the "automatic runtime" compiles JSX into calls to react/jsx-runtime, not React.createElement. React 19 requires it, because ref-as-prop and the faster element creation depend on it.⁴

// source
<Button kind="primary" key={id} ref={btnRef}>Save</Button>

// output (automatic runtime, production)
import { jsx as _jsx } from "react/jsx-runtime";
_jsx(Button, { kind: "primary", ref: btnRef, children: "Save" }, id);

Notice what changed compared with createElement(type, props, ...children):

• children goes into the props object. It is not passed as varargs.
• key is a separate third argument. The compiler pulls it out, so the runtime does not have to scan props for it.
• ref stays in props. That is the React 19 "ref as a prop" change.

react/jsx-runtime exports jsx and jsxs (static children; it differs only in DEV key validation). In production both point to jsxProd. In DEV, jsx/jsxs are dev wrappers, and jsxDEV comes from react/jsx-dev-runtime.⁵

jsxProd and the element shape

jsxProd does very little work, and that is on purpose: it runs for every element in every render.⁶

// packages/react/src/jsx/ReactJSXElement.js (simplified)
export function jsxProd(type, config, maybeKey) {
  let key = null;
  if (maybeKey !== undefined) key = '' + maybeKey;
  if (hasValidKey(config)) key = '' + config.key;   // <div {...props} /> with key spread in

  let props;
  if (!('key' in config)) {
    props = config;               // reuse the compiler-created object as props: zero copy
  } else {
    props = {};
    for (const propName in config) if (propName !== 'key') props[propName] = config[propName];
  }
  return ReactElement(type, key, props, getOwner(), undefined, undefined);
}

The "reuse config as props" fast path is only safe because jsx is a compiler target: the compiler always passes a fresh object literal. createElement cannot assume that, so it always copies. The source comment says exactly this.⁶

ReactElement builds the object itself:⁷

// production shape
{
  $$typeof: REACT_ELEMENT_TYPE,   // Symbol.for('react.transitional.element')
  type,                            // 'div' | function | class | memo/lazy/context object...
  key,                             // string | null
  ref,                             // mirrors props.ref (deprecated accessor)
  props,                           // includes children and ref
}

Details worth knowing:

• $$typeof is a Symbol on purpose. JSON cannot contain Symbols. So a server response that someone tricks into rendering as {type: 'div', props: {dangerouslySetInnerHTML: ...}} is not treated as an element. That is the old XSS defence. In React 19 the symbol is react.transitional.element, not the old react.element.⁸ Elements from a copy of React 18 bundled into the same page are therefore rejected ("Objects are not valid as a React child"). This is often the first sign of a duplicate-React problem.
• element.ref is now a deprecated mirror. The comment says props.ref is the source of truth. In DEV, element.ref is a non-enumerable getter that warns when read.⁷ For forwardRef-free components in 19, ref arrives in props just like any other prop.
• DEV elements are frozen. In DEV, Object.freeze(element.props) and Object.freeze(element) run, and extra non-enumerable fields (_store, _debugInfo, _debugStack, _debugTask) are attached.⁷ Mutating props "works" in production and throws in DEV. Don't do it.
• _owner (DEV only in this version) records which component created the element. It powers owner stacks in error messages.

Elements are immutable descriptions, created fresh on every render. They do not have identity across renders. Fibers do. Reconciliation (see beginWork & Reconciliation) is the step that maps "this element at this position/key" onto "that existing fiber".

ReactSharedInternals: the switchboard

react exports one oddly named object:

// packages/react/src/ReactClient.js
export { ReactSharedInternals as __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, ... }

⁹ Renderers import it through shared/ReactSharedInternals, which is literally React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE.¹⁰ Because the renderer reads it from the react module it was given, both sides share the same object at runtime. The fields:¹¹

Short one-letter keys are used because these properties are read on every hook call and survive minification as property names. Old long names like ReactCurrentDispatcher.current cost bytes and an extra hop.

react-dom has its own internals too. ReactDOMSharedInternals.p holds the current update priority (used by Event System and requestUpdateLane), and .d holds the DOM resource dispatcher for preload and the like.¹²

How useState from react reaches the reconciler

In react, a hook is just a forwarding stub:¹³

// packages/react/src/ReactHooks.js (simplified)
function resolveDispatcher() {
  const dispatcher = ReactSharedInternals.H;
  // DEV: if null, console.error('Invalid hook call...')
  return dispatcher;
}
export function useState(initialState) {
  const dispatcher = resolveDispatcher();
  return dispatcher.useState(initialState);
}

The reconciler installs the real implementation in renderWithHooks, just before it calls your function:¹⁴

// packages/react-reconciler/src/ReactFiberHooks.js (prod branch, simplified)
ReactSharedInternals.H =
  current === null || current.memoizedState === null
    ? HooksDispatcherOnMount     // useState -> mountState
    : HooksDispatcherOnUpdate;   // useState -> updateState
let children = Component(props, secondArg);
// ...
finishRenderingHooks(current, workInProgress, Component); // sets H = ContextOnlyDispatcher

HooksDispatcherOnMount.useState is mountState.¹⁵ When the component returns, finishRenderingHooks resets H to ContextOnlyDispatcher, where every hook except readContext/use is throwInvalidHookError.¹⁶¹⁷ The work loop also wraps the whole render in pushDispatcher/popDispatcher, which sets H = ContextOnlyDispatcher for the duration of renderRootSync/renderRootConcurrent.¹⁸¹⁹

sequenceDiagram
  participant App as Your component
  participant R as react (ReactHooks)
  participant SI as ReactSharedInternals.H
  participant Rec as reconciler (ReactFiberHooks)
  Rec->>SI: H = HooksDispatcherOnMount / OnUpdate
  Rec->>App: Component(props)
  App->>R: useState(0)
  R->>SI: read H
  SI-->>Rec: H.useState(0) = mountState / updateState
  Rec-->>App: [state, setState]
  App-->>Rec: return JSX elements
  Rec->>SI: H = ContextOnlyDispatcher

That explains the three causes listed in the famous "Invalid hook call" error:²⁰

1. Hook called outside render. H is null (no render has started yet) or ContextOnlyDispatcher (between components). You get a DEV console.error or a thrown error.
2. Mismatched React and renderer versions. The renderer's dispatcher lacks a method the react stub calls.
3. Two copies of React. Your component imported react copy B, but react-dom sets H on copy A's internals. Copy B's H stays null. Nothing is "wrong" with the hook. The two switchboards just never meet.

StrictMode double render lives here too

In DEV, if the fiber has StrictLegacyMode, renderWithHooks calls renderWithHooksAgain a second time after the first call.²¹ The source comment is precise about a non-obvious detail: the second call reuses hook state from the first, so useMemo does not recompute on the second pass. To still catch impure memo functions, user functions are double-invoked during the first pass instead. The React 19 upgrade guide describes the visible result: useMemo/useCallback reuse the first render's result during the second render.⁴ This is DEV only. Production never double-renders, so "my effect ran twice" bugs exist only on your machine, by design.

The host config: how the reconciler stays DOM-agnostic

The reconciler imports from ./ReactFiberConfig, but that file only throws:²²

// packages/react-reconciler/src/ReactFiberConfig.js
throw new Error('This module must be shimmed by a specific renderer.');

At build time, Rollup's fork mechanism swaps it for forks/ReactFiberConfig.<renderer>.js.²³ For DOM, that fork re-exports react-dom-bindings/src/client/ReactFiberConfigDOM.²⁴ The host config is a flat list of functions and constants the reconciler calls. A few you'll meet later:

Line numbers for these are in the footnotes.²⁵ Because the host config is resolved at build time and not injected at runtime, calls into it are direct function calls the minifier can inline. A runtime "renderer interface" object would add a dynamic dispatch to every DOM operation.

Putting it in order: what is loaded before anything renders

1. import React from 'react' evaluates ReactSharedInternalsClient: {H: null, A: null, T: null, S: null} (plus DEV fields).¹¹
2. import { createRoot } from 'react-dom/client' evaluates the bundled reconciler and the DOM host config. The event system builds its allNativeEvents registry. The Scheduler picks MessageChannel (browser) or setImmediate (Node) for its host callback (see Lanes & Scheduler).
3. Your module graph evaluates. Every JSX expression at module top level (rare) runs jsx() immediately. Component bodies do not run yet.
4. createRoot(container) builds the FiberRoot and the HostRoot fiber and attaches listeners. See createRoot.
5. root.render(<App />) creates one element (<App />), enqueues it as an update on the HostRoot, and schedules work. See root.render. App itself has still not been called. That happens in the Work Loop.

With the React Compiler

The compiler does not change any of the bootstrap machinery. It rewrites component bodies. The one bootstrap-level touch point is an extra import in compiled modules:

import { c as _c } from "react/compiler-runtime";
function Greeting(props) {
  const $ = _c(2);          // allocate/read a 2-slot memo cache for this fiber
  // ...
}

In React 19, react/compiler-runtime re-exports useMemoCache as c.²⁶ useMemoCache in react is a stub that forwards to the dispatcher like every other hook.²⁷ So _c(n) runs through the same ReactSharedInternals.H path described above and ends in the reconciler's useMemoCache, which keeps the cache array on the fiber's update queue.²⁸ React itself exposes the runtime as __COMPILER_RUNTIME.²⁹ The standalone react-compiler-runtime npm package re-exports React.__COMPILER_RUNTIME.c when present and otherwise polyfills it with a useMemo of a sentinel-filled array, for React 17/18.³⁰ How the compiler decides what goes into those slots is covered in React Compiler, and the runtime effect in With vs Without Compiler.

Summary

The code you import is not the code that does the work. react builds throwaway element objects and owns one shared switchboard, ReactSharedInternals. react-dom carries a private copy of the reconciler, compiled against the DOM host config, and plugs its own dispatcher into that switchboard right before calling your component. So a hook is a forwarding stub whose behaviour depends on what the renderer put in H. Nothing has rendered yet: createRoot builds the root objects next.

Key takeaways

• Package split: react knows nothing about fibers or the DOM, so one component model runs under many renderers.
• jsxProd: key arrives as a separate argument, ref stays in props, and the compiler-created object is reused as props when no key is spread in.
• React elements: immutable, recreated every render, tagged with a $$typeof Symbol JSON cannot contain; fibers, not elements, have identity.
• ReactSharedInternals: the one mutable object both sides share, with slots such as H (hooks dispatcher) and T (current transition).
• Hook stubs: useState from react reads ReactSharedInternals.H and forwards the call.
• renderWithHooks: installs HooksDispatcherOnMount or HooksDispatcherOnUpdate before your component runs, then H is reset to ContextOnlyDispatcher.
• "Invalid hook call": a hook outside render, mismatched versions, or two copies of React whose switchboards never meet.
• Host config: swapped in at build time, so DOM operations are direct function calls, not runtime dispatch.
• React Compiler: _c(n) is useMemoCache and goes through the same H path.

← Prev · Index · Next →