Building a Virtual DOM from Scratch: What I Learned Reverse-Engineering React

Deepmalya Mallick — Thu, 12 Feb 2026 06:36:02 +0000

I used React for a long time before I realized something slightly embarrassing:
I couldn’t actually explain how the Virtual DOM worked.
I knew the rules everyone repeats:

"Don't mutate state"
"Add keys to your lists"
"React diffs the virtual DOM"

But if you asked me what actually happens when setState() runs? I'd fumble through a vague explanation about "reconciliation" and hope you didn't ask follow-up questions.
So I did what any student with too much time during semester break would do: I stopped reading blog posts and built my own Virtual DOM from scratch.
That experiment became Weave — a complete VDOM reconciler written in TypeScript with keyed reconciliation, lifecycle hooks, immutable VNodes, and a live metrics dashboard that visualizes its own internal operations.
This isn't a tutorial. It's what I learned by actually building the thing.

The Problem: Why Virtual DOM Even Exists

Let me show you the most naive way to update the DOM:

function updateCounter(count) {
  document.body.innerHTML = `
    <div>
      <h1>Counter: ${count}</h1>
      <button onclick="updateCounter(${count + 1})">+1</button>
    </div>
  `;
}

This works. For exactly one click.
Then you notice:

The entire DOM tree gets destroyed
Every element gets recreated from scratch
All event listeners re-register
You lose input focus, scroll position, everything

For a toy counter? Maybe acceptable.
For a real app with hundreds of elements? Completely unusable.
The Virtual DOM solves this by adding a middle layer:

Describe what you want as plain JavaScript objects (VNodes)
Compare the old description vs the new one
Generate minimal change instructions (patches)
Apply only those specific changes to the real DOM

Instead of rebuilding everything, you reuse what's already there and update only what changed.
The real challenge isn't applying changes efficiently. It's figuring out what changed in the first place.

Architecture: The One Rule I Refused to Break

Before I wrote any code, I made one non-negotiable decision:
The diffing algorithm cannot know anything about the DOM.
Why? Because comparing two tree structures is pure logic. It shouldn't matter if you're rendering to:

Browser DOM
Canvas
Terminal UI
React Native
Or something completely different

That led me to this layered architecture:

┌───────────────────────────────┐
│           USER CODE           │
│   h('div', props, children)   │
└───────────────────────────────┘
                │
                ▼
┌───────────────────────────────┐
│              CORE             │
│   (Platform-Agnostic Logic)   │
│                               │
│   • VNode creation (immutable)│
│   • __id identity assignment  │
│   • diff(old, new)            │
└───────────────────────────────┘
                │
                ▼
        ┌─────────────────┐
        │     Patch[]     │
        │  (Declarative)  │
        └─────────────────┘
                │
                ▼
┌───────────────────────────────┐
│           RENDERER            │
│                               │
│   • Applies patches           │
│   • Preserves DOM identity    │
│   • Runs lifecycle hooks      │
│   • Tracks metrics            │
└───────────────────────────────┘
                │
                ▼
┌───────────────────────────────┐
│         DOM HOST              │
│      (Platform Layer)         │
│                               │
│   createElement()             │
│   setProp()                   │
│   insert() / remove()         │
└───────────────────────────────┘
                │
                ▼
┌───────────────────────────────┐
│           REAL DOM            │
│   <div><h1>Hello</h1></div>   │
└───────────────────────────────┘

Let me break down what each layer does:

Core Layer (Platform-Agnostic)

This is where the actual diffing happens. It knows nothing about browsers, DOM nodes, or document.createElement().

// From: src/core/types.ts
export interface VNode {
  readonly type: VNodeType;      // 'div', 'span', etc.
  readonly props: VNodeProps;     // { class: 'box', onClick: ... }
  readonly children: VNodeChildren; // 'text' or [VNode, VNode]
  readonly key: VNodeKey;         // For list reconciliation
}

A VNode is just data. No methods, no hidden behavior.
The diff() function takes two trees and returns declarative patches:

// From: src/core/diff.ts
export function diff(
  oldVNode: VNode | null,
  newVNode: VNode | null
): Patch[] {
  // Returns instructions like:
  // [
  //   { type: 'UPDATE_TEXT', vnode: ..., value: 'New text' },
  //   { type: 'SET_PROP', vnode: ..., key: 'class', value: 'active' }
  // ]
}

Renderer Layer (Platform Bridge)

The renderer takes those patches and applies them. It maintains a map of VNode IDs to real DOM nodes:

// From: src/renderer/createRenderer.ts
const nodeMap = new Map<number, Node>();

function commit(patches: Patch[]): void {
  for (const patch of patches) {
    switch (patch.type) {
      case 'UPDATE_TEXT': {
        const node = nodeMap.get(patch.vnode.__id);
        node.textContent = patch.value;
        break;
      }
      // ... handle other patch types
    }
  }
}

Platform Layer (DOM-Specific)

This is the only part that actually touches the browser DOM:

// From: src/platforms/dom/host.ts
export const domHost: HostConfig<DomNode> = {
  createElement(type: string): HTMLElement {
    return document.createElement(type);
  },

  setProp(node: DomNode, key: string, value: unknown): void {
    if (key.startsWith('on') && typeof value === 'function') {
      const eventName = key.slice(2).toLowerCase();
      node.addEventListener(eventName, value as EventListener);
    } else {
      node.setAttribute(key, String(value));
    }
  },

  insert(parent: DomNode, child: DomNode, index: number): void {
    const refNode = parent.childNodes[index] ?? null;
    parent.insertBefore(child, refNode);
  }
  // ... more methods
};

Why this matters: If I want to render to Canvas tomorrow, I only swap out the platform layer. The core diffing algorithm stays exactly the same.
I even enforced this separation with ESLint:

// From: eslint.config.cjs
'import/no-restricted-paths': [
  'error',
  {
    zones: [
      {
        target: './src/core',
        from: ['./src/renderer', './src/platforms'],
        message: 'core must remain platform-agnostic'
      }
    ]
  }
]

If I accidentally try to import DOM code into the core? Build fails. The architecture boundary is enforced at compile time.

Immutability: The Decision That Prevented So Many Bugs

Every VNode in Weave is completely frozen:

// From: src/core/vnode.ts
export function createVNode(
  type: VNodeType,
  props: VNodeProps,
  children: VNodeChildren,
  key: VNodeKey = null
): VNode {
  const vnode: VNode = { type, props, children, key };

  // Freeze everything
  Object.freeze(vnode);
  if (props) Object.freeze(props);
  if (Array.isArray(children)) Object.freeze(children);

  return vnode;
}

At first, this felt unnecessary. "Who would mutate a VNode anyway?"
Turns out, accidentally mutating VNodes is extremely easy when you're debugging and testing different approaches. And when it happens, the bugs are subtle and confusing.
Freezing gives you:

1. Guaranteed immutability

const vnode = h('div', null, 'Hello');
vnode.children = 'World'; // ❌ TypeError in strict mode

2. Fast reference equality checks

if (oldVNode === newVNode) {
  // Guaranteed to be identical - skip diffing entirely
  return [];
}

3. Easier debugging

VNodes can't change after creation
No "who modified this?" mysteries
Data flow is predictable

The trade-off is slightly higher memory usage (more objects created), but it's absolutely worth it.

The Internal __id System: Solving DOM Node Identity

Here's a problem I didn't anticipate early on:
How do you know which DOM node to reuse when the VNode tree changes?
Consider this update:

// Before
const before = h('div', null, [
  h('p', { key: 'a' }, 'Hello'),
  h('p', { key: 'b' }, 'World')
]);

// After  
const after = h('div', null, [
  h('p', { key: 'b' }, 'World'),  // moved up
  h('p', { key: 'a' }, 'Goodbye') // moved down, text changed
]);

The keys tell us semantic identity ('a' is still 'a', 'b' is still 'b').
But when the renderer processes this, how does it know which actual

element in the DOM corresponds to which VNode?

Solution: Internal stable IDs

// From: src/core/vnode.ts
let vnodeId = 0;

export function createVNode(...): VNode {
  const vnode: VNode = { type, props, children, key };

  // Attach non-enumerable __id
  Object.defineProperty(vnode, '__id', {
    value: vnodeId++,
    enumerable: false,  // Won't show in console.log or JSON.stringify
    writable: false,
    configurable: false
  });

  Object.freeze(vnode);
  return vnode;
}

Now the renderer maintains a simple map:

// From: src/renderer/createRenderer.ts
const nodeMap = new Map<number, Node>();

function createNode(vnode: VNode): Node {
  const node = host.createElement(vnode.type);
  nodeMap.set(vnode.__id, node);  // Store the mapping
  return node;
}

When a MOVE patch happens, we can instantly look up the real DOM node and reposition it:

case 'MOVE': {
  const parentNode = nodeMap.get(patch.parent.__id);
  const childNode = nodeMap.get(patch.vnode.__id);

  // Reuse existing DOM node - don't recreate
  host.remove(childNode);
  host.insert(parentNode, childNode, patch.to);
  break;
}

This is when keys finally clicked for me. They're not about micro-optimizations. They're about preserving identity so the renderer knows what to reuse.

Patch-Based Updates: The Core Insight

The diffing algorithm never touches the DOM. It just returns declarative patches:

// From: src/core/patch-types.ts
export type Patch =
  | ReplacePatch      // Replace entire subtree
  | UpdateTextPatch   // Update text content in place
  | InsertPatch       // Add new child at index
  | RemovePatch       // Remove child
  | SetPropPatch      // Set/update property  
  | RemovePropPatch   // Remove property
  | MovePatch         // Reorder child (keyed lists)
  | UpdatePatch;      // Trigger lifecycle hooks

For example, changing text from "Hello" to "World" produces:

[
  {
    type: 'UPDATE_TEXT',
    vnode: previousVNode,
    value: 'World'
  },
  {
    type: 'UPDATE',
    oldVNode: previousVNode,
    newVNode: currentVNode
  }
]

This separation gives you:

1. Pure testability

const patches = diff(oldTree, newTree);
expect(patches).toEqual([
  { type: 'UPDATE_TEXT', value: 'World' }
]);
// No DOM needed!

2. Batching opportunities

Collect patches from multiple updates
Apply them all at once
Minimize layout thrashing

3. Platform flexibility

Same patches work for DOM, Canvas, Terminal
Just swap the renderer

Keyed vs Non-Keyed Reconciliation: The Algorithm That Made It Click

This is where it got really interesting.

Non-Keyed (Simple Index-Based)

Without keys, diffing is straightforward but inefficient:

// From: src/core/diff.ts (non-keyed path)
for (let i = 0; i < max; i++) {
  const oldChild = oldChildren[i] ?? null;
  const newChild = newChildren[i] ?? null;

  if (oldChild === null && newChild !== null) {
    patches.push({ type: 'INSERT', vnode: newChild, index: i });
  }
  else if (oldChild !== null && newChild === null) {
    patches.push({ type: 'REMOVE', vnode: oldChild });
  }
  else if (oldChild && newChild) {
    patches.push(...diffNonNull(oldChild, newChild));
  }
}

Problem: Reordering causes unnecessary updates:

// Before: ['A', 'B', 'C']
// After:  ['C', 'A', 'B']

// Without keys, index-based diff sees:
// Position 0: 'A' → 'C' (UPDATE_TEXT)
// Position 1: 'B' → 'A' (UPDATE_TEXT)  
// Position 2: 'C' → 'B' (UPDATE_TEXT)
// Result: All 3 nodes get their text updated!

Keyed (Identity-Preserving)

With keys, we build a map and track which nodes moved:

// From: src/core/diff.ts (keyed path)
if (hasKeys) {
  // Build lookup map: key → VNode
  const oldKeyMap = new Map<string | number, VNode>();
  oldChildren.forEach(child => {
    if (child.key != null) {
      oldKeyMap.set(child.key, child);
    }
  });

  const usedOld = new Set<VNode>();

  newChildren.forEach((newChild, newIndex) => {
    const key = newChild.key;

    if (key != null && oldKeyMap.has(key)) {
      const oldChild = oldKeyMap.get(key)!;
      usedOld.add(oldChild);

      // Found matching key - reuse the node
      patches.push(...diffNonNull(oldChild, newChild));

      // Check if it moved
      const oldIndex = oldIndexMap.get(oldChild)!;
      if (oldIndex !== newIndex) {
        patches.push({
          type: 'MOVE',
          vnode: oldChild,
          from: oldIndex,
          to: newIndex
        });
      }
    } else {
      // New node - insert it
      patches.push({
        type: 'INSERT',
        vnode: newChild,
        index: newIndex
      });
    }
  });

  // Remove unused old nodes
  oldChildren.forEach(oldChild => {
    if (!usedOld.has(oldChild)) {
      patches.push({ type: 'REMOVE', vnode: oldChild });
    }
  });
}

With keys:

// Before: [A(key='a'), B(key='b'), C(key='c')]
// After:  [C(key='c'), A(key='a'), B(key='b')]

// Keyed diff produces:
// - MOVE C from index 2 → 0
// - MOVE A from index 0 → 1
// - MOVE B from index 1 → 2
// Result: All nodes reused, just repositioned. Zero text updates!

Performance impact:

Without keys: O(n) DOM updates (text changes)
With keys: O(n) MOVE operations, zero DOM recreation

This is why React complains about missing keys. It's not nitpicking — it's the difference between recreating elements and simply moving them.

The Hard Parts (Where I Actually Broke Things)

Challenge 1: DOM Nodes Can't "Move"

This bug took me embarrassingly long to figure out.
DOM nodes don't have a "move" operation. You can only remove and re-insert:

// From: src/renderer/createRenderer.ts
case 'MOVE': {
  const parentNode = nodeMap.get(patch.parent.__id);
  const childNode = nodeMap.get(patch.vnode.__id);

  // ❌ WRONG - trying to be clever
  // host.insert(parentNode, childNode, patch.to);

  // ✅ CORRECT - explicit remove first
  host.remove(childNode);
  host.insert(parentNode, childNode, patch.to);
  break;
}

Why? Because insertBefore() has a side effect: if the node already exists in the parent, it gets moved. But if you're trying to swap adjacent nodes, this breaks:

// Trying to swap [A, B] → [B, A]
// Naive approach:
// 1. Insert B at index 0 → [B, A, B] (B duplicates!)
// 2. Insert A at index 1 → [B, A, B, A] (Both duplicate!)

The fix: Always remove first. It's more explicit and actually works correctly.

Challenge 2: Async Removal Hooks

I wanted to support exit animations, so I added lifecycle hooks:

// From: src/core/types.ts
export interface VNodeHooks<Node = unknown> {
  create?: (vnode: VNode, node: Node) => void;
  update?: (oldVNode: VNode, newVNode: VNode, node: Node) => void;
  remove?: (vnode: VNode, node: Node, done: () => void) => void;
}

The remove hook gets a done callback that controls when removal actually happens:

// From: src/renderer/createRenderer.ts
case 'REMOVE': {
  const node = nodeMap.get(patch.vnode.__id);
  const removeHook = patch.vnode.props?.hooks?.remove;

  const finalizeRemoval = () => {
    host.remove(node);
    metrics.nodes.removed++;
    nodeMap.delete(patch.vnode.__id);
  };

  if (removeHook) {
    // Let the hook control timing
    removeHook(patch.vnode, node, finalizeRemoval);
  } else {
    // No hook - remove immediately
    finalizeRemoval();
  }
  break;
}

Usage:

h('div', {
  hooks: {
    remove(vnode, node, done) {
      // Fade out over 300ms
      node.style.transition = 'opacity 300ms';
      node.style.opacity = '0';

      setTimeout(done, 300); // Call done() when animation finishes
    }
  }
}, 'Goodbye!')

The element stays in the DOM during the animation, then gets removed when done() is called.

Challenge 3: Keeping the Identity Map in Sync

This was a subtle bug that caused mysterious issues.
When you update a VNode, it gets a new internal ID:

const vnode1 = h('div', null, 'Hello'); // __id: 0
const vnode2 = h('div', null, 'World'); // __id: 1 (different ID!)

But the actual DOM node stays the same

.
If the renderer doesn't update its nodeMap, it keeps pointing to the old ID and future patches fail.

The fix: Always emit an UPDATE patch:

// From: src/core/diff.ts
function diffNonNull(prev: VNode, next: VNode): Patch[] {
  const patches: Patch[] = [];

  // ... all the actual diffing logic ...

  // ✅ CRITICAL: Always emit UPDATE to sync IDs
  patches.push({
    type: 'UPDATE',
    oldVNode: prev,
    newVNode: next
  });

  return patches;
}

Then the renderer updates the mapping:

// From: src/renderer/createRenderer.ts
case 'UPDATE': {
  const oldV = patch.oldVNode as VNodeWithId;
  const newV = patch.newVNode as VNodeWithId;
  const node = nodeMap.get(oldV.__id);

  if (node) {
    // Update the mapping
    nodeMap.delete(oldV.__id);
    nodeMap.set(newV.__id, node);

    // Run lifecycle hook if present
    newV.props?.hooks?.update?.(oldV, newV, node);
  }
  break;
}

Now the map stays in sync across all updates.

The Dashboard: Proof It Actually Works

At some point I got tired of guessing if optimizations were working. So I built a live metrics dashboard using Weave itself

These are the high-level stats:

Updates (23): Total number of root.update() calls
Avg Time (0.65ms): Average duration of each update cycle (diff + patch application)
Active Nodes (1017): Current number of DOM nodes being managed
Total Patches (3005): Cumulative patch operations applied since initialization

The fact that average update time is sub-millisecond shows the VDOM overhead is negligible.

Patch Timeline (Left Middle)

This is my favorite part. It shows recent patch operations in reverse chronological order:

05:30:27.519 UPDATE node
05:30:27.519 UPDATE node
05:30:27.519 UPDATE node
05:30:27.519 UPDATE_TEXT Text → "20"

Each row shows:

Timestamp: When the patch was applied (millisecond precision)
Patch Type: UPDATE, UPDATE_TEXT, INSERT, etc.
Description: What changed (e.g., text content, VNode ID)

When you click the +1 button, you see new UPDATE patches appear immediately. It's the VDOM watching itself work.
Patch Operations (Right Middle)
This heatmap shows the distribution of patch types:

UPDATE (2034): Most common - fired on every node that's reused
INSERT (320): New nodes added
REMOVE (282): Nodes removed
UPDATE_TEXT (223): Text content changes
SET_PROP (145): Property updates
REPLACE (1): Full subtree replacement (rare)
MOVE (0): No list reorderings yet
REMOVE_PROP (0): No properties removed yet

The horizontal bars give you a visual sense of what operations dominate. In this session, UPDATE patches far outnumber everything else — which is exactly what you want. It means nodes are being reused, not recreated.

Update Duration Trend (Bottom Left)
This bar chart shows performance over the last 20 updates. Each bar represents one update() call.
You can see the durations are very consistent (all around 0.6-0.8ms) with a few spikes. Those spikes happen when:

Large batch updates occur
Many nodes are inserted/removed at once
Complex prop updates happen

For a production system, you'd watch this chart for regressions. If a change causes update times to spike, you know something broke.

Interactive Demo (Bottom Right)

The counter (currently at "21") with +1/-1 buttons.
Here's the meta part: This counter is built with Weave. When you click +1:

The counter VNode updates: h('div', null, String(21)) → h('div', null, String(22))
The diff algorithm generates patches
The renderer applies them
All of this gets recorded in the metrics
The dashboard updates itself (also using Weave) to show the new patches

It's Weave observing itself in real-time.

The entire dashboard is ~300 lines of code using the same h() function and update mechanism:

// From: demo/dashboard/dashboard.ts
function Dashboard(metrics: RendererMetrics, counter: number): VNode {
  return h('div', { class: 'dashboard-container' }, [
    // Performance metrics
    h('div', { class: 'metrics-grid' }, [
      MetricCard('Updates', String(metrics.updates + 1), 'total'),
      MetricCard('Avg Time', metrics.avgUpdateDurationMs.toFixed(2), 'ms'),
      MetricCard('Active Nodes', String(metrics.nodes.active), 'nodes'),
      MetricCard('Total Patches', String(metrics.patches.total), 'ops')
    ]),

    // Patch timeline
    PatchTimeline(metrics.patchHistory),

    // Patch heatmap
    PatchHeatmap(metrics),

    // Update duration chart
    LiveChart(metrics.history.durations),

    // Interactive demo
    InteractiveDemo(counter, onIncrement, onDecrement)
  ]);
}

function renderDashboard(): void {
  const vnode = Dashboard(dashboardRoot.metrics, demoCounter);
  dashboardRoot.update(vnode);
}

Watching this run made everything "click" in a way reading React source code never did.

What I Actually Learned

Immutability Isn't Academic
Freezing objects felt wasteful when I first did it. "Why prevent mutation that won't happen?"
Turns out, accidental mutations do happen during development. And when they do, the bugs are incredibly subtle.
Frozen VNodes eliminated an entire class of issues I didn't even know existed.
The DOM Is Always the Bottleneck
I spent time optimizing the diff algorithm — reducing allocations, caching results, etc.
Then I profiled it.
VDOM overhead: 0.01-0.05ms
Actual DOM manipulation: 0.5-2ms
The abstraction isn't the slow part. It never was.
Separation of Concerns Is Hard But Worth It
Keeping the core platform-agnostic required constant discipline:

Resisting shortcuts ("just import document here")
Designing clean interfaces
Fighting the urge to optimize for one specific platform

But now:

The core is fully unit-testable (no jsdom required)
The renderer is swappable
Adding Canvas/Terminal support is just a new host layer

The architecture actually scales.

Keys Aren't About Performance Micro-Optimizations Before building this, I thought keys were about making React "go faster." That's not it. Keys are about preserving identity so the reconciler knows which nodes to reuse vs recreate. Without them, reordering a list destroys and recreates everything. With them, nodes just move. It's not a speedup. It's a completely different algorithm.

What I'd Do Differently

Add Fragment Support from the Start

Right now, every VNode needs a single root:

// ❌ Not supported
return [
  h('li', null, 'Item 1'),
  h('li', null, 'Item 2')
];

// ✅ Must wrap
return h('ul', null, [
  h('li', null, 'Item 1'),
  h('li', null, 'Item 2')
]);

Fragments would eliminate unnecessary wrapper elements.

Build a Component Abstraction Earlier

The current API is pure VNodes. No state, no lifecycle beyond hooks.
Adding lightweight components would make Weave actually practical:

function Counter({ initialValue }) {
  const [count, setCount] = useState(initialValue);

  return h('div', null, [
    h('h1', null, String(count)),
    h('button', { onclick: () => setCount(count + 1) }, '+1')
  ]);
}

This is the natural next step.

Profile Much Earlier

I didn't add metrics until after building most of the core.
Some decisions (like always freezing children arrays) might have been different if I'd measured from the start.
Next time: metrics first, optimizations second.

What's Next

Short-term (weeks):

Fragment support - Allow returning arrays without wrappers
Component abstraction - Lightweight state management
Performance benchmarks - Compare against React/Preact

Medium-term (months):

Async rendering - Interruptible updates, priority-based scheduling
Additional platforms - Canvas renderer, Terminal UI
Developer tools - Browser extension, component inspector

Long-term (ambitious):

JSX support - Better DX than raw h() calls
Server-side rendering - Render to HTML string + client hydration
Small ecosystem - Router, forms, state management

Try It Yourself

Github :

Symphony007 / Weave---VirtualDOM

A renderer-agnostic Virtual DOM engine built from scratch

Weave VDOM

A production-grade Virtual DOM reconciler built from scratch in TypeScript. Weave implements a platform-agnostic diffing algorithm with keyed reconciliation, lifecycle hooks, and strict immutability guarantees.

Overview

Weave is a minimal yet complete Virtual DOM implementation that demonstrates the core concepts behind modern UI libraries like React, Vue, and Preact.

It provides:

Platform-agnostic core — The diffing algorithm has zero DOM dependencies
Efficient reconciliation — Keyed and non-keyed diffing with minimal DOM operations
Type safety — Full TypeScript support with strict type checking
Performance metrics — Built-in instrumentation for debugging and optimization
Production-ready patterns — Immutable VNodes, stable identity, and declarative patches

Why Weave?

Weave was built to understand Virtual DOM internals from first principles. Unlike production libraries that prioritize features and bundle size, Weave prioritizes clarity and correctness.

Every design decision is explicit, making it an excellent learning resource or foundation for custom renderers.

Quick Start

Installation

…

View on GitHub

DEV Community: Deepmalya Mallick