~/alexsh.blog

$ cat react-internals/02-fiber-architecture.md

Fiber Architecture

February 9, 20261 min readpart 02/13

Fiber is React's internal reconciliation engine, introduced in React 16 as a complete rewrite. It's the most important architectural concept in modern React.

Why Fiber Exists

The old Stack Reconciler processed the tree recursively and synchronously. Once it started, it couldn't stop — a large update could block the main thread for hundreds of milliseconds, causing jank. Fiber makes rendering interruptible by breaking work into small units that can be paused, resumed, or aborted.

What Is a Fiber?

A Fiber is a plain JavaScript object representing a unit of work. There's one for every component instance, DOM element, or React node in your tree — a mutable, linked-list-based work-in-progress tree.

codetsx
// Simplified Fiber node
{
  // Identity
  tag: FunctionComponent | HostComponent | ...,
  type: App,
  key: null,

  // Tree structure (linked list, not array children)
  return: parentFiber,
  child: firstChildFiber,
  sibling: nextSiblingFiber,

  // State & Props
  memoizedState: { count: 0 },  // Head of hooks linked list
  pendingProps: { title: 'World' },

  // Effects
  flags: Update | Placement | Deletion,  // Bitmask
  subtreeFlags: Update,                  // Bubbled from children

  // Scheduling
  lanes: 0b0000000000000000001,  // Priority bitmask

  // Double buffering
  alternate: workInProgressFiber,
}

Linked List Traversal

Unlike typical trees with arrays of children, Fiber uses child → sibling → return pointers. This lets React traverse iteratively with a while loop instead of recursively — which is what makes work interruptible. At any point, React knows exactly where it left off.

diagramtext
       App
        │  (child)
      Header ──→ Content ──→ Footer  (sibling links)
        │          │
      Logo      Article ──→ Sidebar

Double Buffering

React maintains two Fiber trees at all times. The current tree reflects what's on screen. The workInProgress tree is where changes are applied. Each Fiber has an alternate pointer to its counterpart. On commit, React swaps — the WIP becomes current. This is double buffering, borrowed from graphics.

diagramtext
current tree:           workInProgress tree:
  App (count: 0)  ←→  App (count: 1)      ← alternate pointers
   │                    │
  Div              →  Div
   │                    │
  Span "0"         →  Span "1"             ← Update flag

Further reading