React Core Architecture

react-core-architecture

Quick Reference

Architecture Layers

Core Principles

React Element vs Component

Critical Warnings

NEVER mutate state or props during rendering -- rendering MUST be a pure calculation. Mutations cause inconsistent UI and break concurrent features.

NEVER rely on render timing or count -- React MAY call your component multiple times, skip renders, or pause and resume rendering. StrictMode double-invokes components in development.

NEVER perform side effects in the render phase (network requests, subscriptions, DOM mutations) -- ALWAYS use useEffect or event handlers for side effects.

NEVER use inheritance to share behavior between components -- ALWAYS use composition (children, render props, or custom hooks).

NEVER call root.render() where hydrateRoot() is needed -- for server-rendered HTML, ALWAYS use hydrateRoot to preserve server markup and attach event handlers.

NEVER assume synchronous DOM updates after root.render() -- rendering is asynchronous. Use flushSync() ONLY when synchronous behavior is explicitly required.

Rendering Model

JSX Compilation

JSX is syntactic sugar for React.createElement() calls:

// JSX (what you write)
<Greeting name="Taylor" />

// Compiled output (what React sees)
createElement(Greeting, { name: 'Taylor' })

The returned React element is an immutable object:

{
  type: Greeting,       // Component function or string tag
  props: { name: 'Taylor' },
  key: null,
  ref: null
}

ALWAYS use capital letters for component names in JSX -- lowercase names resolve to HTML tags, not components.

Three-Phase Rendering Cycle

React updates the screen in three sequential steps:

After the commit phase, the browser paints the updated screen.

Render Phase (Pure)

• React calls your component function to produce a new element tree
• Compares the new tree with the previous tree (reconciliation)
• In concurrent mode (React 18+), this phase is interruptible -- React can pause, resume, or discard work
• MUST be pure: no side effects, no DOM mutations, no subscriptions

Commit Phase (Synchronous)

• React applies the minimal set of DOM changes identified during reconciliation
• Runs useLayoutEffect cleanup and setup synchronously
• The browser paints the screen
• Runs useEffect cleanup and setup asynchronously after paint

Reconciliation Algorithm

React's diffing strategy uses two key heuristics:

1. Different element types produce different trees -- React tears down the old subtree and builds a new one
2. Keys identify which children remain stable across re-renders -- ALWAYS provide stable keys for list items

// React preserves <input> because the element type and position match
<div>
  <input value={text} />  {/* Same position, same type = preserved */}
</div>

Fiber Architecture (React 16+)

The Fiber reconciler replaced the legacy stack reconciler to enable:

Each fiber node represents a component instance and contains:

• type -- the component function or host element tag
• stateNode -- the DOM node (for host elements) or component instance
• child, sibling, return -- tree navigation pointers
• memoizedState -- the linked list of hooks for this component
• pendingProps, memoizedProps -- current and previous props
• lanes -- priority bits for scheduling (React 18+)

NEVER access fiber internals directly -- they are private implementation details that change between React versions.

Component Lifecycle

Function Component Lifecycle

Mount:      Component called -> Elements created -> DOM inserted -> Effects run
Update:     State/props change -> Component re-called -> Reconciliation -> DOM patched -> Effects re-run
Unmount:    Effect cleanups run -> DOM removed

Entry Point: createRoot

import { createRoot } from 'react-dom/client';
import { StrictMode } from 'react';
import App from './App';

const root = createRoot(document.getElementById('root')!, {
  onCaughtError: (error, errorInfo) => {
    console.error('Caught:', error, errorInfo.componentStack);
  },
  onUncaughtError: (error, errorInfo) => {
    console.error('Uncaught:', error, errorInfo.componentStack);
  },
});

root.render(
  <StrictMode>
    <App />
  </StrictMode>
);

ALWAYS wrap the root in <StrictMode> during development to detect impure renders, missing effect cleanups, and deprecated APIs.

Component Tree Model

Render Tree

The render tree represents the component hierarchy for a single render pass:

• Nodes are React components (not HTML elements)
• Root node is the top-level component passed to root.render()
• Top-level components near the root affect performance of all descendants
• Leaf components at the bottom are frequently re-rendered

The tree changes dynamically with conditional rendering -- different state produces different subtrees.

Unidirectional Data Flow

State (parent) --> Props (child) --> Props (grandchild)
     ^                                      |
     |                                      |
     +-------- Callbacks (events) <---------+

Data flows DOWN through props. Communication UP happens through callback functions passed as props. NEVER pass data upward by mutating parent state from a child without using a callback.

StrictMode Behavior (Development Only)

StrictMode checks run ONLY in development. They have zero impact on production builds.

React 18 vs React 19

Reference Links

• references/examples.md -- Working code examples for rendering, lifecycle, and tree structure
• references/api-table.md -- React core type reference and API signatures
• references/anti-patterns.md -- What NOT to do, with explanations

Official Sources

• https://react.dev/learn/render-and-commit
• https://react.dev/learn/understanding-your-ui-as-a-tree
• https://react.dev/reference/react/createElement
• https://react.dev/reference/react-dom/client/createRoot
• https://react.dev/reference/react/StrictMode
• https://react.dev/blog/2024/04/25/react-19