From React to NestJS Master · Part 3 of 3

In Part 1 we built Hexagonal Architecture — swappable databases behind clean ports. In Part 2 we added CQRS and Events — Redux for the backend. Now in Part 3 we add Event Sourcing: Git version control plus Redux DevTools time travel, but for your entire database.

What you’ll walk away with

By the end of this article you’ll understand Event Sourcing (storing every state change as an immutable event), the Event Store (the repository that holds all your events), Rehydration (rebuilding current state by replaying events), Snapshots (the performance escape hatch), and finally how all three parts of this series snap together into one coherent architecture.

The Problem Event Sourcing Solves

Imagine you’re building a collaborative document editor — think Google Docs. You have two choices for how to store state.

Option 1: Store only the current document.

const document = {
  id: 'doc-123',
  content: 'Hello World',
  lastModified: '2024-01-15T10:00:00Z'
};
// ❌ You can't see what changed
// ❌ You can't undo to a specific point
// ❌ You can't debug "how did this typo appear?"
// ❌ Two people editing at once = lost changes

Option 2: Store every change.

const events = [
  { type: 'INSERT', position: 0, text: 'H', timestamp: '10:00:01' },
  { type: 'INSERT', position: 1, text: 'e', timestamp: '10:00:02' },
  { type: 'DELETE', position: 5, text: ' ', timestamp: '10:00:06' },
  { type: 'INSERT', position: 5, text: '!', timestamp: '10:00:07' },
];
// ✅ Perfect audit trail
// ✅ Time travel to any point
// ✅ Real-time collaboration
// ✅ Undo/redo forever

Event Sourcing is exactly this pattern for your backend. And if you already know Git, you already know Event Sourcing — you just don’t know you know it yet.

Git concept Event Sourcing concept Why they’re the same Commit Event Immutable record of a change .git folder Event Store Storage for all events git log Event Stream Full ordered history git checkout Rehydration Rebuild state from history Git tag Snapshot Save point for performance git bisect Time travel debugging Find when the bug appeared Merge conflict Concurrency error Two changes to the same state

If you understand Git, you already understand Event Sourcing. The only difference: Git tracks code. Event Sourcing tracks data.

Traditional Database vs. Event Sourcing

The difference becomes visceral when you ask real business questions.

With a traditional database you only ever see the final state:

SELECT * FROM alarms WHERE id = 'alm-123';
-- { id: 'alm-123', name: 'Fire', severity: 'critical', acknowledged: true }
-- Questions you CANNOT answer:
-- Was the severity ever changed?
-- Who acknowledged it and when?
-- What was the original severity?
-- How long between creation and acknowledgment?

With Event Sourcing you store every transition:

const alarmEvents = [
  {
    id: 'evt-1', streamId: 'alm-123', type: 'AlarmCreated', position: 0,
    data: { name: 'Fire', severity: 'high' },
    timestamp: '2024-01-15T10:00:00Z', userId: 'system'
  },
  {
    id: 'evt-2', streamId: 'alm-123', type: 'AlarmSeverityUpdated', position: 1,
    data: { oldSeverity: 'high', newSeverity: 'critical' },
    timestamp: '2024-01-15T10:05:00Z', userId: 'operator-456'
  },
  {
    id: 'evt-3', streamId: 'alm-123', type: 'AlarmAcknowledged', position: 2,
    data: { acknowledgedBy: 'supervisor-789', notes: 'Fire confirmed' },
    timestamp: '2024-01-15T10:10:00Z', userId: 'supervisor-789'
  }
];
// NOW every question has an answer:
// Original severity?   → 'high' (event 0)
// Who acknowledged?    → supervisor-789 at 10:10
// Response time?       → 10 minutes (event 2 − event 0)
// Who escalated it?    → operator-456 at 10:05

The events are the source of truth. The “current state” you see in a traditional database is just a projection — a convenience view derived from the full history.

Building Event Sourcing Step by Step

Step 1: The Event Store schema

Think of this as your .git folder — append-only, ordered, indexed by stream.

// src/shared/infrastructure/event-store/event.schema.ts
@Schema({ timestamps: true })
export class EventDocument extends Document {
  @Prop({ required: true, index: true })
  streamId: string;      // Which aggregate — e.g. 'alarm:alm-123'
  @Prop({ required: true })
  type: string;          // Event type — e.g. 'AlarmCreated'
  @Prop({ required: true })
  position: number;      // Order in stream: 0, 1, 2…
  @Prop({ required: true, type: Object })
  data: Record<string, any>;
  @Prop({ type: Object })
  metadata?: Record<string, any>;  // Who, when, why, correlation ID
}
// Unique index prevents duplicate positions in a stream —
// just like Git prevents two commits at the same hash.
EventSchema.index({ streamId: 1, position: 1 }, { unique: true });

Step 2: The Aggregate Root

The aggregate is the Git repo. It can apply events to change its state, track uncommitted changes, and rebuild itself from a history of past events.

// src/alarms/domain/alarm.aggregate.ts
export class AlarmAggregate extends AggregateRoot {
  private _id: string;
  private _name: string;
  private _severity: string;
  private _isAcknowledged: boolean = false;
  private _version: number = 0;
  private _changes: any[] = [];  // Staging area — like git add
  // Apply an event to update state (like git apply)
  private applyEvent(event: any, isFromHistory = false) {
    const handler = this[`on${event.constructor.name}`];
    if (!handler) throw new Error(`No handler for ${event.constructor.name}`);
    handler.call(this, event);
    if (!isFromHistory) this._changes.push(event);
  }
  // Business method — creates and applies an event (like git commit)
  createAlarm(name: string, severity: string, facilityId: string) {
    if (!name || name.length < 3)
      throw new Error('Alarm name must be at least 3 characters');
    this.applyEvent(new AlarmCreatedEvent(this.generateId(), name, severity, facilityId));
  }
  onAlarmCreatedEvent(event: AlarmCreatedEvent) {
    this._id = event.alarmId;
    this._name = event.name;
    this._severity = event.severity;
    this._version = 1;
  }
  acknowledgeAlarm(acknowledgedBy: string) {
    if (this._isAcknowledged) throw new Error('Alarm already acknowledged');
    this.applyEvent(new AlarmAcknowledgedEvent(this._id, acknowledgedBy));
  }
  onAlarmAcknowledgedEvent(event: AlarmAcknowledgedEvent) {
    this._isAcknowledged = true;
    this._acknowledgedAt = event.timestamp;
  }
  getUncommittedEvents() { return this._changes; }   // git status
  commit() { this._changes = []; }                   // git reset (after push)
  // Rebuild from history — this is git checkout
  loadFromHistory(events: any[]) {
    for (const event of events) {
      this.applyEvent(event, true);
      this._version++;
    }
  }
}

Step 3: The Event Store service

// src/shared/infrastructure/event-store/mongo-event-store.ts
@Injectable()
export class MongoEventStore {
  async appendEvents(streamId: string, events: any[], expectedVersion: number) {
    const eventsWithPositions = events.map((event, index) => ({
      streamId,
      type: event.constructor.name,
      position: expectedVersion + index + 1,
      data: this.serializeEvent(event),
      metadata: { timestamp: new Date(), correlationId: this.generateCorrelationId() }
    }));
    try {
      await this.eventModel.insertMany(eventsWithPositions);
    } catch (error) {
      if (error.code === 11000) {  // Duplicate key — like a merge conflict
        throw new ConcurrencyError(
          `Stream ${streamId} was modified. Expected version ${expectedVersion}`
        );
      }
      throw error;
    }
  }
  async getEvents(streamId: string) {
    const docs = await this.eventModel.find({ streamId }).sort({ position: 1 }).exec();
    return docs.map(doc => this.deserializeEvent(doc));
  }
  async getEventsFromPosition(streamId: string, fromPosition: number) {
    const docs = await this.eventModel
      .find({ streamId, position: { $gt: fromPosition } })
      .sort({ position: 1 }).exec();
    return docs.map(doc => this.deserializeEvent(doc));
  }
}

Step 4: Rehydration — git checkout for your data

// src/alarms/application/services/alarm-rehydrator.service.ts
@Injectable()
export class AlarmRehydrator {
  // Rebuild the current state — like git checkout main
  async rehydrate(alarmId: string): Promise<AlarmAggregate> {
    const events = await this.eventStore.getEvents(`alarm:${alarmId}`);
    if (events.length === 0) throw new Error(`Alarm ${alarmId} not found`);
    const alarm = new AlarmAggregate();
    alarm.loadFromHistory(events);
    return this.eventPublisher.mergeObjectContext(alarm);
  }
  // Rebuild state at a specific moment — like git checkout <commit-hash>
  async rehydrateAtTime(alarmId: string, timestamp: Date): Promise<AlarmAggregate> {
    const allEvents = await this.eventStore.getEvents(`alarm:${alarmId}`);
    const eventsUpToTime = allEvents.filter(e => e._metadata.timestamp <= timestamp);
    const alarm = new AlarmAggregate();
    alarm.loadFromHistory(eventsUpToTime);
    return this.eventPublisher.mergeObjectContext(alarm);
  }
}

Step 5: Command handlers that use the event store

Every command handler follows the same pattern: rehydrate the aggregate, apply business logic, append the resulting events, clear the staging area.

@CommandHandler(AcknowledgeAlarmCommand)
export class AcknowledgeAlarmHandler implements ICommandHandler<AcknowledgeAlarmCommand> {
  async execute(command: AcknowledgeAlarmCommand) {
    // 1. Rebuild aggregate from history (git checkout latest commit)
    const alarm = await this.rehydrator.rehydrate(command.alarmId);
    // 2. Apply business logic — creates new events internally
    alarm.acknowledgeAlarm(command.acknowledgedBy);
    // 3. Append only the new events (git commit + push)
    await this.eventStore.appendEvents(
      `alarm:${command.alarmId}`,
      alarm.getUncommittedEvents(),
      alarm.version - alarm.getUncommittedEvents().length
    );
    // 4. Clear staging area
    alarm.commit();
  }
}

Snapshots — The Performance Escape Hatch

The problem: an aggregate that has processed 10,000 events must replay all 10,000 every time it’s rehydrated. Over time this becomes a real performance issue.

The solution: periodically save a snapshot of the current state — exactly like a Git tag — and only replay events after that snapshot.

@Injectable()
export class AlarmRehydratorWithSnapshots {
  async rehydrate(alarmId: string): Promise<AlarmAggregate> {
    const streamId = `alarm:${alarmId}`;
    // Find the latest snapshot (like finding the latest tag)
    const latestSnapshot = await this.snapshotModel
      .findOne({ streamId }).sort({ version: -1 }).exec();
    let alarm: AlarmAggregate;
    let eventsSinceSnapshot: any[];
    if (latestSnapshot) {
      // Restore from snapshot, then replay only the delta
      alarm = new AlarmAggregate();
      alarm.loadFromSnapshot(latestSnapshot.state);
      eventsSinceSnapshot = await this.eventStore.getEventsFromPosition(
        streamId, latestSnapshot.version
      );
    } else {
      alarm = new AlarmAggregate();
      eventsSinceSnapshot = await this.eventStore.getEvents(streamId);
    }
    alarm.loadFromHistory(eventsSinceSnapshot);
    // Create a new snapshot every 100 events
    if (alarm.version - (latestSnapshot?.version || 0) >= 100) {
      await this.createSnapshot(alarm);
    }
    return alarm;
  }
}

The performance difference is dramatic:

Total events Without snapshots With snapshots (every 100) Speedup 100 Replay 100 Replay 100 1× 1,000 Replay 1,000 Snapshot + replay 100 10× 10,000 Replay 10,000 Snapshot + replay 100 100× 100,000 Replay 100,000 Snapshot + replay 100 1,000×

Snapshots keep rehydration O(1) + O(100) regardless of how much history has accumulated.

Time Travel in Practice

Let’s trace what happens when an alarm is created, escalated, and acknowledged — and how you can rewind to any moment.

// 1. Create alarm at 10:00
await commandBus.execute(new CreateAlarmCommand('Fire', 'high', 'plant-1'));
// Event store: [AlarmCreated { severity: 'high' }]
// 2. Operator escalates at 10:05
await commandBus.execute(new UpdateAlarmSeverityCommand('alm-123', 'critical'));
// Event store: [..., AlarmSeverityUpdated { high → critical }]
// 3. Supervisor acknowledges at 10:10
await commandBus.execute(new AcknowledgeAlarmCommand('alm-123', 'supervisor-456'));
// Event store: [..., AlarmAcknowledged { by: supervisor-456 }]
// ── Current state ──────────────────────────────────────────
const current = await rehydrator.rehydrate('alm-123');
// { severity: 'critical', acknowledged: true }
// ── Time travel to just after creation ─────────────────────
const atCreation = await rehydrator.rehydrateAtTime('alm-123', new Date('10:00'));
// { severity: 'high', acknowledged: false }
// ── Answer business questions from the event log ───────────
const events = await eventStore.getEvents('alarm:alm-123');
const responseTime = events[2].timestamp - events[0].timestamp; // 10 minutes
const escalatedBy  = events[1].metadata.userId;                 // operator-789
const origSeverity = events[0].data.severity;                   // 'high'

None of this is possible with a traditional database. Every question gets answered directly from the immutable event log.

The Complete Architecture

After three parts, the full picture looks like this:

Presentation routes requests. CQRS separates reads from writes so each can be optimised independently. Event Sourcing makes the event log the single source of truth. Infrastructure sits behind ports — swappable without touching business logic.

Each layer has exactly one job. That’s the whole game.

A Real-World Flow

An IoT temperature sensor fires. Here’s everything that happens end to end.

// 1. Frontend sends: POST /api/alarms
// { name: 'Temperature Critical', severity: 'high', facilityId: 'plant-123' }
// 2. Controller dispatches a command
@Post()
async create(@Body() dto: CreateAlarmDto) {
  return this.commandBus.execute(new CreateAlarmCommand(dto));
}
// 3. Command handler creates and stores events
@CommandHandler(CreateAlarmCommand)
class CreateAlarmHandler {
  async execute(command) {
    const alarm = new AlarmAggregate();
    alarm.createAlarm(command.name, command.severity, command.facilityId);
    const events = alarm.getUncommittedEvents();
    await this.eventStore.appendEvents(`alarm:${alarm.id}`, events, 0);
    events.forEach(e => this.eventBus.publish(e));
    return { id: alarm.id };
  }
}
// 4. Event handler keeps the Read DB in sync
@EventsHandler(AlarmCreatedEvent)
class UpdateReadDbHandler {
  async handle(event: AlarmCreatedEvent) {
    await this.readRepository.upsert({
      id: event.alarmId, name: event.name,
      severity: event.severity, status: 'pending',
      severityColor: this.getColor(event.severity)
    });
  }
}
// 5. Saga detects a dangerous pattern — 3 alarms in 5 seconds
@Saga()
class PatternDetectionSaga {
  detectThreeInFiveSeconds(events$) {
    return events$.pipe(
      ofType(AlarmCreatedEvent),
      groupBy(e => e.facilityId),
      mergeMap(group => group.pipe(
        bufferTime(5000),
        filter(events => events.length >= 3),
        map(events => new NotifySupervisorCommand(events[0].facilityId, events.length))
      ))
    );
  }
}
// 6. Meanwhile the dashboard query is fast — reads from the denormalized Read DB
@Get('dashboard/:facilityId')
async getDashboard(@Param('facilityId') id: string) {
  return this.queryBus.execute(new GetDashboardQuery(id));
}

The write path is event-sourced and auditable. The read path is a denormalized, pre-shaped projection optimised for the UI. They evolve independently.

Testing Event Sourcing

Because aggregates are pure functions of their event history, testing is straightforward.

describe('AlarmRehydrator', () => {
  it('should rebuild aggregate from events', async () => {
    const events = [
      new AlarmCreatedEvent('alm-1', 'Fire', 'high', 'plant-1'),
      new AlarmAcknowledgedEvent('alm-1', 'supervisor-1')
    ];
    eventStore.getEvents.mockResolvedValue(events);
    const alarm = await rehydrator.rehydrate('alm-1');
    expect(alarm.name).toBe('Fire');
    expect(alarm.severity).toBe('high');
    expect(alarm.isAcknowledged).toBe(true);
  });
  it('should reject concurrent modifications', async () => {
    // Two handlers rehydrate the same aggregate simultaneously
    const alarm1 = await rehydrator.rehydrate('alm-1');
    const alarm2 = await rehydrator.rehydrate('alm-1');
    alarm1.acknowledgeAlarm('supervisor-1');
    alarm2.acknowledgeAlarm('supervisor-2');
    await expect(save(alarm1)).resolves.not.toThrow();
    await expect(save(alarm2)).rejects.toThrow(ConcurrencyError);
  });
});

No database spin-up needed. Give the aggregate a sequence of events, assert on the resulting state. That’s it.

When to Use (and When to Skip) Event Sourcing

Event Sourcing carries real costs. Be honest about whether the benefits justify them for your situation.

Use it when:

• Audit requirements are non-negotiable. Financial systems, healthcare records, compliance logs — if you must answer “who changed what and when” with certainty, events are the only honest answer.
• You need time travel debugging. When a production bug is “impossible to reproduce,” being able to replay the exact sequence of events that caused it is worth its weight in gold.
• Undo/redo is a product feature. Compensating events cleanly reverse any past operation without destructive updates.
• The system is collaborative. Real-time concurrent editing (Google Docs, Figma-style) is far easier to reason about when the source of truth is an ordered event log.

Skip it when:

• It’s a CRUD app. Todo lists, admin panels, basic internal tools. The complexity cost is enormous and the benefits are zero.
• Storage is constrained. Events take 10–100× more space than storing only current state.
• Your team is small and the deadline is real. Event store, snapshots, rehydration, concurrency handling — it’s a steep learning curve for a junior team under time pressure.
• History simply doesn’t matter. If no one will ever ask “what did this look like six months ago?”, you’re paying all the cost for none of the value.

The decision tree: start with Hexagonal Architecture (always worth it). Add CQRS when your reads are slowing your writes. Add Event Sourcing when your business needs a permanent, queryable history.

The Complete Frontend → Backend Mapping

After three parts, here’s the full picture of how your existing frontend intuition maps to backend patterns.

Frontend concept Backend concept Part Why they’re analogous React component Controller 1 Entry point, delegates work Custom hook Service 1 Orchestrates operations Context provider Module 1 Provides dependencies useState Aggregate state 1 Holds current state Redux action Command 2 Describes what should change Redux reducer Command handler 2 Applies state changes Redux selector Query 2 Reads state efficiently useEffect (basic) Event handler 2 Reacts to state changes useEffect (complex) Saga 2 Complex reactive logic Redux DevTools Event Store 3 Records all state changes Time travel debugging Rehydration 3 Replays past states Git commit Event 3 Immutable change record git checkout Rehydration 3 Restores state from history Git tag Snapshot 3 Performance save point Merge conflict Concurrency error 3 Two changes to the same state

The Challenge: Build a Banking System

The best way to solidify this is to build something yourself. Here’s a starter — finish it.

class BankAccount extends AggregateRoot {
  private balance: number = 0;
  createAccount(initialBalance: number) {
    // Emit AccountCreatedEvent
  }
  deposit(amount: number, reference: string) {
    // Emit MoneyDepositedEvent
  }
  withdraw(amount: number, reference: string) {
    if (amount > this.balance) throw new Error('Insufficient funds');
    // Emit MoneyWithdrawnEvent
  }
  onAccountCreatedEvent(e: AccountCreatedEvent)  { this.balance = e.initialBalance; }
  onMoneyDepositedEvent(e: MoneyDepositedEvent)  { this.balance += e.amount; }
  onMoneyWithdrawnEvent(e: MoneyWithdrawnEvent)  { this.balance -= e.amount; }
}

Your checklist: can you create an account? Deposit and withdraw? Does it prevent overdrawing? Can you view the full transaction history? Rewind to any past balance? Does a Saga detect 3 withdrawals in under 5 minutes and raise a fraud alert?

If you can do all of that, you’ve genuinely understood this series.

The Aha Moment

If you understand:           Then you already understand:
─────────────────────        ─────────────────────────────
Redux actions/reducers    →  CQRS commands/handlers
Redux DevTools            →  Event Store
Git commits               →  Events
git checkout              →  Rehydration
Git tags                  →  Snapshots
React useEffect           →  Sagas

The only difference: in the frontend, state lives in memory.
In the backend, state lives in databases and event stores.

That’s the whole secret. The mental models you’ve built over years of frontend work translate directly. You were always closer to backend architecture than you thought.

Series Recap

Part 1 — Hexagonal Architecture: separate business logic from infrastructure. The application defines ports; infrastructure implements adapters. Always worth the small upfront cost.

Part 2 — CQRS + Events: separate reads from writes so each can evolve and scale independently. Sagas handle the complex reactive logic that would otherwise tangle your command handlers.

Part 3 — Event Sourcing: make the event log the source of truth. Current state is just a projection. Snapshots keep performance linear. Rehydration gives you time travel for free.

Start simple. Add each layer only when you feel the problem it solves. Hexagonal architecture is nearly free. CQRS pays off when reads start hurting writes. Event Sourcing pays off when history and auditability are first-class requirements.

If this series helped you understand backend architecture as a frontend engineer — share it with someone else making the jump.

Follow for: real-world case studies, performance optimization deep dives, microservices with these patterns, and testing strategies for event-sourced systems.

From React to NestJS Master (Part 3) : Event Sourcing: Git for Your Database — And the Complete… was originally published in JavaScript in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.

In Part 1 we built a Hexagonal architecture that lets us swap databases like changing state managers. Now we’ll add the patterns that make complex systems manageable: CQRS (like Redux actions + selectors) and Event-Driven Architecture (like useEffect on steroids).

The Problem with CRUD

You’ve probably built a Twitter-like feed before. One endpoint that does everything — reads, writes, validation, caching. It works until it doesn’t.

The problem is that reads and writes have completely different requirements:

Write Operations Read Operations Need validation rules Need FAST performance Need data integrity Can be denormalized Happen less frequently Happen CONSTANTLY Complex business logic Simple data shaping One item at a time Hundreds at once

In React terms: this is like using the same component for both editing AND displaying a form, with all validation and submission logic mixed with rendering.

CQRS — The Core Insight

CQRS = Command Query Responsibility Segregation.

COMMAND (Write)              QUERY (Read)
──────────────────           ──────────────────
"Change something"           "Get something"
Returns void (or ID)         Returns data
Has side effects             No side effects
Validates business rules     Optimized for speed
Goes through event bus       Direct database access

The React analogy that makes it click:

// Redux — you already know this pattern
const action   = { type: 'ALARM_CREATED', payload: { text: '...' } }; // Command
const reducer  = (state, action) => { /* applies business rules */ };  // Command Handler
const selector = (state) => state.alarms.filter(a => !a.hidden);      // Query
function AlarmApp() {
  const dispatch = useDispatch(); // For commands
  const alarms   = useSelector(selector); // For queries
}

CQRS is exactly this pattern — but for your entire backend:

Redux Concept CQRS Concept Action Command Reducer Command Handler Selector Query Store (write) Write Database Store (read) Read Database dispatch() CommandBus useSelector() QueryBus

Building CQRS Step by Step

Install the package

npm install @nestjs/cqrs

Define a Command (like a Redux action)

// src/alarms/application/commands/create-alarm.command.ts
export class CreateAlarmCommand {
  constructor(
    public readonly name: string,
    public readonly severity: string,
    public readonly facilityId: string,
  ) {}
}

Create the Command Handler (like a Redux reducer)

// src/alarms/application/commands/create-alarm.command-handler.ts
@CommandHandler(CreateAlarmCommand)
export class CreateAlarmCommandHandler implements ICommandHandler<CreateAlarmCommand> {
  constructor(
    private readonly alarmRepository: AlarmRepository,
    private readonly eventBus: EventBus
  ) {}
  async execute(command: CreateAlarmCommand): Promise<Alarm> {
    // 1. Validate (domain logic)
    const severity = Severity.create(command.severity);
    // 2. Create entity (domain logic)
    const alarm = new Alarm(this.generateId(), command.name, severity, command.facilityId);
    // 3. Persist (write DB via port)
    await this.alarmRepository.save(alarm);
    // 4. Broadcast what happened
    this.eventBus.publish(new AlarmCreatedEvent(alarm));
    return alarm;
  }
}

Notice what’s NOT here: no @Get(), no HTTP status codes, no database queries. This handler works whether you call it from HTTP, GraphQL, WebSockets, or a CLI.

Define a Query (like a Redux selector)

// src/alarms/application/queries/get-dashboard-alarms.query.ts
export class GetDashboardAlarmsQuery {
  constructor(
    public readonly facilityId: string,
    public readonly limit: number = 50,
    public readonly onlyUrgent: boolean = false
  ) {}
}

Create the Query Handler

@QueryHandler(GetDashboardAlarmsQuery)
export class GetDashboardAlarmsQueryHandler implements IQueryHandler<GetDashboardAlarmsQuery> {
  constructor(
    // A DIFFERENT repository — optimized for reads
    private readonly readRepository: AlarmReadRepository
  ) {}
  async execute(query: GetDashboardAlarmsQuery): Promise<DashboardAlarmDto[]> {
    let alarms = await this.readRepository.findByFacility(query.facilityId);
    if (query.onlyUrgent) {
      alarms = alarms.filter(a => a.isUrgent);
    }
    return alarms.slice(0, query.limit).map(alarm => ({
      id: alarm.id,
      title: alarm.name,
      severityColor: alarm.severityColor,
      time: this.formatRelativeTime(alarm.createdAt),
      requiresAction: !alarm.isAcknowledged && alarm.isUrgent,
    }));
  }
}

No business logic. No validation. Just fast data fetching shaped for the UI.

The Controller — now clean

@Controller('alarms')
export class AlarmsController {
  constructor(
    private readonly commandBus: CommandBus,
    private readonly queryBus: QueryBus
  ) {}
  @Post()
  async create(@Body() body: CreateAlarmDto) {
    const alarm = await this.commandBus.execute(
      new CreateAlarmCommand(body.name, body.severity, body.facilityId)
    );
    return { id: alarm.id, requiresAttention: alarm.requiresImmediateAttention() };
  }
  @Get('dashboard/:facilityId')
  async getDashboard(@Param('facilityId') facilityId: string) {
    return this.queryBus.execute(new GetDashboardAlarmsQuery(facilityId));
  }
}

Domain Events — The Backend’s Custom Event System

The problem events solve

In React, when a child component changes, you bubble an event up to the parent. The child doesn’t know who’s listening — it just announces what happened.

Domain events are the exact same pattern:

• Your business logic (the “child”) emits events when something important happens
• Other parts of the system (the “parent”) react to those events
• The business logic doesn’t know or care what reacts

Event Fan-out: one event, multiple independent handlers

Without events (tightly coupled):

// ❌ BAD: AlarmService knows about notifications
class AlarmService {
  async createAlarm(input) {
    const alarm = new Alarm(...);
    await this.repository.save(alarm);
    // Alarm creation now knows about notification logic
    const recentAlarms = await this.repository.findRecent(input.facilityId, 5000);
    if (recentAlarms.length >= 3) {
      await this.notificationService.notifySupervisor(input.facilityId);
    }
    return alarm;
  }
}

With events (loosely coupled):

// ✅ GOOD: AlarmService just announces what happened
class AlarmService {
  async createAlarm(input) {
    const alarm = new Alarm(...);
    await this.repository.save(alarm);
    // Published once. Never looks back.
    this.eventBus.publish(new AlarmCreatedEvent(alarm));
    return alarm;
  }
}
// Elsewhere — completely separate code, zero coupling to AlarmService
@EventsHandler(AlarmCreatedEvent)
class UpdateDashboardHandler {
  async handle(event: AlarmCreatedEvent) {
    await this.readRepository.upsert({ id: event.alarmId, ... });
  }
}

Adding a new handler (SlackNotifier, AuditLogger, AnalyticsTracker) requires zero changes to AlarmService. Just register a new @EventsHandler.

Eventual Consistency — the trade-off

When writes and reads are separated, the read DB is updated asynchronously after the event fires. This means there’s a brief window where data is stale.

The write DB is updated at t=5ms. The event fires at t=6ms. The read DB catches up at t=7ms. The HTTP response goes out at t=8ms.

You accept a few milliseconds of staleness in exchange for a read DB that’s always fast and never blocked by write transactions. For most UIs, this is completely acceptable.

Sagas — Complex useEffect With Better Tools

The problem sagas solve

Business requirement: “If a facility has 3 alarms within 5 seconds, notify the supervisor. But only notify once per minute.”

This is the kind of useEffect you dread writing:

// React equivalent — painful and fragile
useEffect(() => {
  const facilityGroups = new Map();
  const interval = setInterval(() => {
    for (const [facilityId, events] of facilityGroups) {
      const recentEvents = events.filter(e => Date.now() - e.timestamp < 5000);
      if (recentEvents.length >= 3) {
        const lastNotify = lastNotifyTime.get(facilityId);
        if (!lastNotify || Date.now() - lastNotify > 60000) {
          notifySupervisor(facilityId);
          lastNotifyTime.set(facilityId, Date.now());
        }
      }
    }
  }, 1000);
  return () => clearInterval(interval);
}, []);

Sagas make this declarative using RxJS — the same library React Query and Redux Observable use.

The Saga Pipeline

@Injectable()
export class AlarmPatternSaga {
  @Saga()
  detectThreeAlarmsInFiveSeconds(events$: Observable<any>): Observable<ICommand> {
    return events$.pipe(
      ofType(AlarmCreatedEvent),           // 1. filter type
      groupBy(event => event.facilityId),  // 2. split by facility
      mergeMap(facilityEvents$ => facilityEvents$.pipe(
        bufferTime(5000),                  // 3. collect 5 seconds
        filter(events => events.length >= 3), // 4. need 3+
        throttleTime(60000),               // 5. once per minute
        map(events => new NotifySupervisorCommand(
          events[0].facilityId,
          events.length
        ))
      ))
    );
  }
}

Seeing it happen live

The saga watches the event stream silently. The alarm service never knows it exists. The notification fires automatically when the pattern matches.

Another saga: the timeout pattern

Business requirement: “If an alarm isn’t acknowledged within 15 minutes, escalate to the manager.”

@Injectable()
export class EscalationSaga {
  @Saga()
  escalateUnacknowledgedAlarms(events$: Observable<any>): Observable<ICommand> {
    return events$.pipe(
      ofType(AlarmCreatedEvent),
      mergeMap(alarmCreated =>
        race(
          // Stream 1: wait for acknowledgment
          events$.pipe(
            ofType(AlarmAcknowledgedEvent),
            filter(ack => ack.alarmId === alarmCreated.alarmId),
            first()
          ),
          // Stream 2: wait 15 minutes
          timer(900000).pipe(map(() => alarmCreated))
        ).pipe(
          filter(result => result instanceof AlarmCreatedEvent),
          map(() => new EscalateAlarmCommand(alarmCreated.alarmId))
        )
      )
    );
  }
}

If the alarm is acknowledged before 15 minutes: Stream 1 wins, race() cancels Stream 2. If 15 minutes pass with no acknowledgment: Stream 2 wins, escalation fires. Your alarm creation code knows none of this exists.

The Complete Flow

Let’s trace a single POST /alarms request through the entire system:

t = 0ms   POST /alarms
t = 1ms   Controller → CommandBus
t = 2ms   Command Handler validates
t = 5ms   Alarm saved to PostgreSQL (write DB)
t = 6ms   AlarmCreatedEvent published
t = 7ms   Event Handler updates MongoDB (read DB)
t = 8ms   HTTP 201 returned to frontend
t = 10ms  Frontend receives response
t = 15ms  Frontend queries GET /alarms/dashboard
t = 18ms  Fast response from MongoDB (no joins)
t = 5000ms Saga detects 3rd alarm from same facility
t = 5001ms NotifySupervisorCommand dispatched
t = 5002ms Email sent to supervisor

Total: HTTP request served in 8ms. Complex pattern detected at 5 seconds. The alarm creation code never had to know about the notification.

Testing the CQRS + Event System

The biggest benefit of CQRS and events is testability. Each layer tests in complete isolation.

Testing a command handler

describe('CreateAlarmCommandHandler', () => {
  let handler: CreateAlarmCommandHandler;
  let mockRepository: jest.Mocked<AlarmRepository>;
  let mockEventBus: jest.Mocked<EventBus>;
  beforeEach(() => {
    mockRepository = { save: jest.fn() } as any;
    mockEventBus   = { publish: jest.fn() } as any;
    handler        = new CreateAlarmCommandHandler(mockRepository, mockEventBus);
  });
  it('should create and save an alarm', async () => {
    const command = new CreateAlarmCommand('Fire', 'high', 'plant-1');
    const result  = await handler.execute(command);
    expect(mockRepository.save).toHaveBeenCalled();
    expect(mockEventBus.publish).toHaveBeenCalledWith(expect.any(AlarmCreatedEvent));
    expect(result.name).toBe('Fire');
  });
  it('should reject invalid severity', async () => {
    const command = new CreateAlarmCommand('Fire', 'invalid', 'plant-1');
    await expect(handler.execute(command)).rejects.toThrow('Invalid severity');
    expect(mockRepository.save).not.toHaveBeenCalled();
  });
});

No HTTP server. No database. No file system. Just pure logic.

Testing a saga

describe('AlarmPatternSaga', () => {
  it('should notify after 3 alarms in 5 seconds', (done) => {
    const saga    = new AlarmPatternSaga();
    const events$ = of(
      new AlarmCreatedEvent('1', 'Fire',  'high',   'plant-1', new Date()),
      new AlarmCreatedEvent('2', 'Smoke', 'medium', 'plant-1', new Date()),
      new AlarmCreatedEvent('3', 'Heat',  'high',   'plant-1', new Date())
    );
    saga.detectThreeAlarmsInFiveSeconds(events$).subscribe(command => {
      expect(command).toBeInstanceOf(NotifySupervisorCommand);
      expect(command.facilityId).toBe('plant-1');
      done();
    });
  });
});

When Should You Use CQRS + Events?

Use CQRS when:

• Your read and write performance requirements differ significantly
• GET endpoints are slow because of complex joins on the write DB
• You need multiple read shapes (dashboard, mobile, API)
• You need an audit trail — events are immutable records

Skip it when:

• It’s simple CRUD with no complex business logic
• You need strong read-your-writes consistency
• Small team or tight deadline — two models doubles maintenance surface
• You haven’t felt the pain yet — add it when slow queries actually hurt

The golden rule: start with a simple architecture. Add CQRS only when you feel the pain of mixing reads and writes.

Part 2 Summary

CQRS = Commands (writes) + Queries (reads) separated

• Commands = Redux actions (change state, validate, persist, emit events)
• Queries = Redux selectors (fast, denormalized reads)

Domain Events = Announcements from business logic, no coupling

• @EventsHandler = addEventListener for your domain

Sagas = Complex event stream processing with RxJS

• ofType → groupBy → bufferTime → filter → throttleTime → map
• Like useEffect with proper tools for timing and grouping

The complete flow:

• HTTP → Controller → CommandBus → Handler → WriteDB → Event
• Event → EventHandler → ReadDB (eventual consistency, ~2ms)
• Event → Saga → Command → Side Effect (pattern detection, ~5000ms)

The “aha!” moment:

CQRS is just Redux for your backend. Sagas are just useEffect with better timing tools.

What’s Coming in Part 3

Part 3 adds Event Sourcing — which is like Git version control for your database:

• Event Store = the .git folder for your data
• Rehydration = git checkout — rebuild any past state
• Snapshots = Git tags — performance optimization for large streams
• Time travel debugging = git bisect for production bugs

We’ll build a system where you can answer: “What did this alarm look like at 3:47 PM last Tuesday?” — and get the exact answer by replaying events.

Series Navigation

Part 1: Hexagonal Architecture — read it Part 2: CQRS & Event-Driven Architecture ← you are here Part 3: Event Sourcing (coming soon)

Did this help? Clap if you want Part 3!

Questions? Drop them in the comments. I read every single one.

Resources

• NestJS CQRS documentation
• RxJS operators reference

Quick Reference: CQRS + Events Cheatsheet

Concept React Equivalent NestJS Syntax Command Redux Action class CreateAlarmCommand {} Command Handler Redux Reducer @CommandHandler(CreateAlarmCommand) Query Redux Selector class GetAlarmsQuery {} Query Handler Selector function @QueryHandler(GetAlarmsQuery) Event Custom DOM event class AlarmCreatedEvent {} Event Handler addEventListener @EventsHandler(AlarmCreatedEvent) Saga Complex useEffect @Saga() watchForPatterns(events$) Command Bus dispatch() commandBus.execute(command) Query Bus useSelector() queryBus.execute(query) Event Bus EventEmitter eventBus.publish(event)

From React to NestJS Master: A Frontend Engineer’s Journey to Backend Architecture (Part 2) was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

This series assumes you know React and have basic NestJS knowledge. Every concept is explained through frontend analogies you already understand.

The Problem You Already Know

You’ve built React components before. And at some point, you’ve probably built one that did way too much.

Fetching data. Holding state. Running business logic. Rendering JSX. All in one place.

You know that’s wrong. You’ve refactored it. You know how to fix it.

Here’s the thing: the default NestJS structure has the exact same problem. And the fix is the exact same pattern — just with different names.

Watch how one component doing everything becomes four clean, separated concerns.

What NestJS Gives You (and Why It’s Not Enough)

When you run nest new, you get a controller that does everything:

// ❌ BAD: Controller handling everything
@Controller('alarms')
export class AlarmsController {
  private alarms = []; // In-memory "database"
  @Post()
  create(@Body() createAlarmDto: CreateAlarmDto) {
    // Business logic mixed with HTTP handling
    const alarm = {
      id: Date.now().toString(),
      ...createAlarmDto,
      isAcknowledged: false,
      createdAt: new Date(),
    };
    this.alarms.push(alarm);
    return alarm;
  }
  @Get()
  findAll() {
    return this.alarms; // Direct data access
  }
  @Patch(':id/acknowledge')
  acknowledge(@Param('id') id: string) {
    const alarm = this.alarms.find(a => a.id === id);
    if (!alarm) throw new NotFoundException();
    alarm.isAcknowledged = true;
    return alarm;
  }
}

Sound familiar? That’s the monolith AlarmList component all over again.

Same problems:

• Business logic stuck in the controller
• Can’t reuse the acknowledge logic elsewhere
• Hard to test without making HTTP calls
• Can’t switch from in-memory to a real database without rewriting everything

How You’d Fix This in React

Before fixing the backend, let’s see how you’d fix the React component:

// ✅ GOOD: Separated concerns
// 1. Custom hook for data fetching (Service layer)
function useAlarms() {
  const [alarms, setAlarms] = useState([]);
  useEffect(() => {
    alarmAPI.getAll().then(setAlarms);
  }, []);
  const acknowledgeAlarm = async (id) => {
    await alarmAPI.acknowledge(id);
    setAlarms(alarms.map(a =>
      a.id === id ? {...a, isAcknowledged: true} : a
    ));
  };
  return { alarms, acknowledgeAlarm };
}
// 2. Pure utility function (Domain logic)
function getSeverityColor(severity) {
  const colors = { high: 'red', medium: 'yellow', low: 'green' };
  return colors[severity];
}
// 3. Presentational component (Controller)
function AlarmList() {
  const { alarms, acknowledgeAlarm } = useAlarms();
  // ... renders UI only
}
// 4. API client (Adapter)
const alarmAPI = {
  getAll: () => fetch('/api/alarms').then(r => r.json()),
  acknowledge: (id) => fetch(`/api/alarms/${id}/acknowledge`, { method: 'POST' })
};

Notice what happened:

• useAlarms hook can be used in multiple components
• getSeverityColor is testable in isolation
• alarmAPI can be swapped (fetch → axios → GraphQL)
• AlarmList is clean and focused

Hexagonal Architecture Is Just This — With Backend Names

Here’s the reveal. Every frontend pattern you just saw has an exact backend equivalent.

Every row is a concept you already know. Only the name changed.

The mapping is precise:

ReactNestJS / HexagonalWhy they’re the sameComponentControllerBoth receive input, delegate work, never own business logicContext ProviderNestJS ModuleBoth inject dependencies into the scope belowCustom HookApplication ServiceBoth orchestrate without knowing implementation detailsRedux SliceDomain EntityBoth hold state transitions and pure business rulesZod / PropTypesValue ObjectBoth validate at the boundary and reject invalid inputTypeScript InterfacePort (abstract class)Both define a contract without implementationfetch / axiosAdapterBoth implement the contract defined above

The Key Insight: One Arrow Points the Wrong Way

Watch for the teal arrow. It’s the only one pointing up — and that’s the whole point.

The dependency rule in normal code flows downward: UI → Service → Database. Hexagonal breaks this at exactly one place.

The Application Service says: “I need a repository with these methods.” It defines the interface (Port). Then the database adapter implements that interface — the dependency points from infrastructure up toward the application.

This means:

• Your domain and application code never import from your database layer
• You can swap databases without touching a single line of business logic
• You can test the entire application layer with a fake in-memory adapter

Building It — Step by Step

Here’s how the project structure emerges, one layer at a time:

Each folder is a layer. Each file lives exactly where its responsibility says it should.

The folder structure:

src/alarms/
├── domain/
│   ├── value-objects/severity.vo.ts   ← Pure validation, zero deps
│   └── alarm.entity.ts                 ← Business rules (acknowledge, etc.)
├── application/
│   ├── ports/alarm-repository.port.ts  ← The contract (abstract class)
│   └── services/alarm.service.ts       ← Orchestrates domain + port
├── infrastructure/
│   ├── in-memory/in-memory-alarm.repository.ts
│   └── postgres/postgres-alarm.repository.ts
├── presenters/
│   └── http/alarms.controller.ts       ← Only file that knows about HTTP
└── alarms.module.ts                    ← Wires everything together

Step 2: The Domain Layer (Pure Business Rules)

// src/alarms/domain/value-objects/severity.vo.ts
export class Severity {
  private constructor(private readonly value: string) {}
  static create(value: string): Severity {
    const valid = ['low', 'medium', 'high', 'critical'];
    if (!valid.includes(value)) {
      throw new Error(`Severity must be one of: ${valid.join(', ')}`);
    }
    return new Severity(value);
  }
  getValue(): string { return this.value; }
  isUrgent(): boolean { return this.value === 'high' || this.value === 'critical'; }
  getColor(): string {
    return { low: 'green', medium: 'yellow', high: 'orange', critical: 'red' }[this.value];
  }
}

This code has zero dependencies. No HTTP, no database, no NestJS. Copy it to any TypeScript project and it runs. That’s the domain layer.

Step 3: The Entity

// src/alarms/domain/alarm.entity.ts
export class Alarm {
  private isAcknowledged: boolean = false;
  constructor(
    public readonly id: string,
    public readonly name: string,
    public readonly severity: Severity,
    public readonly facilityId: string,
    public readonly createdAt: Date = new Date()
  ) {}
  acknowledge(): void {
    if (this.isAcknowledged) {
      throw new Error('Alarm already acknowledged'); // Business rule!
    }
    this.isAcknowledged = true;
  }
  requiresImmediateAttention(): boolean {
    return this.severity.isUrgent() && !this.isAcknowledged;
  }
  getStatus(): 'pending' | 'acknowledged' {
    return this.isAcknowledged ? 'acknowledged' : 'pending';
  }
}

Step 4: The Port (The Contract)

// src/alarms/application/ports/alarm-repository.port.ts
// Abstract class = interface that survives TypeScript compilation
// NestJS needs classes for dependency injection
export abstract class AlarmRepository {
  abstract save(alarm: Alarm): Promise<void>;
  abstract findAll(): Promise<Alarm[]>;
  abstract findById(id: string): Promise<Alarm | null>;
  abstract findByFacility(facilityId: string): Promise<Alarm[]>;
}

This is the React equivalent of defining interface DataService before implementing it. Your components depend on the interface. Then you pass either Firebase or your custom backend.

Step 5: The Application Service

// src/alarms/application/services/alarm.service.ts
@Injectable()
export class AlarmService {
  // Depends on the ABSTRACTION (port), not the implementation
  constructor(private readonly alarmRepository: AlarmRepository) {}
  async createAlarm(input: {
    name: string; severity: string; facilityId: string;
  }): Promise<Alarm> {
    const severity = Severity.create(input.severity);  // Domain validation
    const alarm = new Alarm(Date.now().toString(), input.name, severity, input.facilityId);
    await this.alarmRepository.save(alarm);            // Uses the port
    return alarm;
  }
  async acknowledgeAlarm(id: string): Promise<void> {
    const alarm = await this.alarmRepository.findById(id);
    if (!alarm) throw new Error('Alarm not found');
    alarm.acknowledge();                               // Business rule from domain
    await this.alarmRepository.save(alarm);
  }
}

Notice what’s NOT here: no @Post(), no HTTP status codes, no database queries.

Steps 6 & 7: Two Adapters, One Interface

// In-memory (for development & testing)
@Injectable()
export class InMemoryAlarmRepository extends AlarmRepository {
  private alarms = new Map<string, Alarm>();
  async save(alarm: Alarm): Promise<void> { this.alarms.set(alarm.id, alarm); }
  async findAll(): Promise<Alarm[]> { return Array.from(this.alarms.values()); }
  async findById(id: string): Promise<Alarm | null> { return this.alarms.get(id) || null; }
  async findByFacility(facilityId: string): Promise<Alarm[]> {
    return (await this.findAll()).filter(a => a.facilityId === facilityId);
  }
}
// PostgreSQL (for production)
@Injectable()
export class PostgresAlarmRepository extends AlarmRepository {
  constructor(
    @InjectRepository(AlarmEntity)
    private readonly repo: Repository<AlarmEntity>
  ) { super(); }
  async save(alarm: Alarm): Promise<void> {
    await this.repo.save(this.toEntity(alarm));
  }
  // ... same interface, different engine
}

Step 8: The Controller

// src/alarms/presenters/http/alarms.controller.ts
@Controller('alarms')
export class AlarmsController {
  constructor(private readonly alarmService: AlarmService) {}
  @Post()
  async create(@Body() body: CreateAlarmDto) {
    const alarm = await this.alarmService.createAlarm(body);
    return {
      id: alarm.id,
      severity: alarm.severity.getValue(),
      severityColor: alarm.severity.getColor(),
      status: alarm.getStatus(),
    };
  }
  @Patch(':id/acknowledge')
  async acknowledge(@Param('id') id: string) {
    await this.alarmService.acknowledgeAlarm(id);
    return { message: 'Alarm acknowledged successfully' };
  }
}

The Payoff — One Line Swaps the Database

Watch the toggle flip. Watch nothing else change.

// src/alarms/alarms.module.ts
@Module({
  controllers: [AlarmsController],
  providers: [
    AlarmService,
    {
      provide: AlarmRepository,
      useClass: InMemoryAlarmRepository, // ← Change ONLY this line
      // useClass: PostgresAlarmRepository,
    },
  ],
})
export class AlarmsModule {}

That’s it. One line. Controller, Service, Domain — none of them know which database you’re using.

Your frontend doesn’t know the difference either. GET /alarms returns the same shape regardless.

When Should You Use This Pattern?

The short version:

Use Hexagonal when:

• You might switch databases (SQL → NoSQL, adding Redis)
• You support multiple APIs (REST + GraphQL + WebSocket)
• The team is large enough that boundaries help coordination
• Business logic must be testable without a real database

Skip it when:

• It’s a simple CRUD app with no complex rules
• You’re building a prototype that needs to move fast
• You’re certain the infrastructure will never change
• The team is one or two people on a short-lived project

The default should always be simplicity. Hexagonal is there when complexity earns it.

Part 1 Summary

You’ve learned that Hexagonal Architecture is not a foreign concept. It’s the same separation-of-concerns pattern you already use in React — just with backend names.

What you knewWhat you learnedComponentControllerCustom HookApplication ServiceRedux SliceDomain EntityTypeScript InterfacePortfetch / axiosAdapterContext ProviderNestJS Module

The key insight: the application defines what it needs (Port), infrastructure provides it (Adapter). The dependency arrow points up — on purpose.

What’s Coming in Part 2

In Part 2 we build on this foundation:

• Commands — like Redux actions, but for the backend write side
• Queries — like Reselect selectors, optimised for reads
• Events — like DOM events, but across your whole system
• Sagas — like useEffect with complex timing — we'll detect "3 alarms in 5 seconds" and notify a supervisor without the alarm creation code knowing anything about notifications

Did this help? Clap if you want Part 2!

Questions? Drop them in the comments. I read every single one.

Resources

• NestJS Documentation
• Hexagonal Architecture — Alistair Cockburn

Series navigation: Part 1: Hexagonal Architecture ← you are here Part 2: CQRS & Event-Driven Architecture (coming soon) Part 3: Event Sourcing (coming soon)

From React to NestJS Master: A Frontend Engineer’s Journey to Backend Architecture (Part 1) was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Series: How React Works Under the Hood This is the final article. If you haven’t read Parts 1–8, this article won’t land the way it should. Go back and start there.

Series: How React Works Under the Hood Part 1: Motivation Behind React Fiber: Time Slicing & Suspense Part 2: Why React Had to Build Its Own Execution Engine Part 3: How React Finds What Actually Changed Part 4: The Idea That Makes Suspense Possible Part 5: The React Lifecycle From the Inside Part 6: How State Actually Works Part 7: The Trap of Vibe Coding useCallback Part 8: Server Components & Hydration: The Real Story

Eight Articles. One Question.

In Part 1, Dan Abramov stood in front of a room in Iceland and asked:

“With vast differences in computing power and network speed, how do we deliver the best user experience for everyone?”

We’ve spent eight articles building the answer. But we’ve never seen all the pieces working together at once. We’ve seen Fiber explained. The Scheduler explained. The Reconciler. Algebraic effects. Lifecycle. State. Performance. Server Components. Each one in isolation.

This article puts them together. Not as a summary — as a story. One user. One interaction. Every layer of React underneath it.

By the end, you’ll see that everything we built across eight articles was always one system.

The User

She opens a product search page on a mid-range Android phone — the kind of device hundreds of millions of people actually use. Her connection is decent but not fast. She’s looking for headphones.

She types. She clicks. She adds something to her cart.

From her perspective: the page loads, she types, results appear, she clicks a button, the cart updates. Four seconds of her life.

Underneath those four seconds, every system in this series ran. Let’s trace it.

The Page Loads

The request hits the server. This is Part 8’s world.

Server Components run — async, directly querying the database. The product catalog, the navigation, the page layout. None of this code ships to her phone. It renders on the server and becomes the RSC payload — a JSON description of the UI that streams to the client in chunks. Her phone gets real HTML almost immediately, not a white screen waiting for JavaScript.

While the HTML is visible, React starts hydration in the background. It walks the server-rendered DOM and matches each node to its Fiber counterpart — attaching event listeners, storing references, making the page interactive. Because React 18 uses the same Lane priority system from Part 3, if she taps something before hydration finishes, React jumps to that boundary first. The rest of the tree waits. Her tap doesn’t go ignored.

The page is ready. She types.

She Types “h”

This is where Parts 2, 3, and 6 all meet.

A change event fires. React calls setQuery('h'). Calling setQuery doesn't immediately update anything — it creates an update object, drops it into a global buffer, and marks a trail called childLanes on every ancestor of the search input fiber, all the way to the root. This is how React knows where work is waiting without walking the entire tree.

The Scheduler sees the update. Because this is a user interaction, it’s SyncLane — the highest priority. It runs synchronously. The call stack equivalent of "drop everything and handle this."

React walks the Fiber tree following the trail of childLanes. Every branch with childLanes === 0 is skipped instantly — the footer, the recommendations panel, the filters sidebar. React touches only what needs to change. The input updates. The character appears on screen.

That took a few milliseconds. She doesn’t notice. She keeps typing.

The Results Need to Update

Here’s the problem that Part 1 opened with — still alive, still relevant.

Filtering 10,000 products on every keystroke is expensive. If React treated the results update with the same urgency as the input update, every character she types would block until the filtering finished. The input would lag. The experience would feel broken.

This is exactly Dan’s typing + chart demo from 2018. The chart is the results list. It has to update. But it shouldn’t block the input.

The fix is startTransition — wrapping the expensive update so React knows it can wait. The input still updates immediately at SyncLane. The results update in the background at TransitionLane, interruptibly:

setQuery(e.target.value);                          // urgent — runs now
startTransition(() => setResults(filter(query)));  // deferrable — runs when free

That’s the entire mechanism. startTransition tells React: this update is real but not urgent. Internally, React assigns it a TransitionLane instead of SyncLane. The Scheduler now has two tasks — the keystroke at the top, the results render below it.

The results render begins using the concurrent work loop — the one that checks shouldYield() after every fiber. She types another character. A new SyncLane keystroke arrives. React abandons the results render mid-tree, handles the keystroke — she sees it immediately — then starts the results render again with the new query.

isPending tells you the transition is in progress, so you can show a spinner or dim the old results while new ones load. The old results stay visible until the render completes. She never sees a blank list.

This is the Git metaphor from Part 1 made real: the keystroke is always the hotfix on main. The results render is always the feature branch. React rebases automatically.

What if you can’t wrap the setter?

Sometimes the state lives in a child component or a library you don’t control. useDeferredValue solves this — it gives you a deferred copy of a value that React renders at lower priority, interruptibly, without you needing to touch the setter:

const deferredQuery = useDeferredValue(query);
// ResultList receives deferredQuery — renders at TransitionLane, same mechanism

The practical rule: use useTransition when you own the setter, useDeferredValue when you own the value but not where it comes from.

React Finds What Changed

She paused typing. The results render runs to completion. This is Part 3.

React walks the ResultList fiber, runs the component function, gets new JSX. The Reconciler compares old to new. Each product has a key prop — its ID. React builds a map of old fibers keyed by product ID. For each new product, it looks up the existing fiber. Found: reuse it, update only what changed. Not found: create it. Products no longer in results: mark for deletion.

React doesn’t touch the DOM during any of this. It marks fibers with flags — insert this, update that, delete this — and bubbles those flags up the tree. By the time it reaches the root, every decision about what needs to change is recorded. Nothing has changed in the DOM yet.

The DOM Updates

The Commit phase runs — synchronous, uninterruptible. The two Fiber trees swap. The workInProgress tree becomes current. What was being built in the background is now the source of truth.

DOM operations execute in order: deletions first, then insertions, then updates. Products that disappeared are removed. New products are inserted. Changed cards get their props updated directly on the existing DOM node — no recreation.

The browser paints. She sees the filtered results.

She Clicks “Add to Cart”

The click fires. setCartCount(c => c + 1) is called. Same machinery as the keystroke — SyncLane, update queued, trail marked up to the root, Scheduler fires synchronously.

React walks the trail. Everything outside the Header subtree has childLanes === 0 — the results list, the filters, the footer — all skipped in one check each. React touches only the Header and its CartIcon child.

The render runs. The commit runs. Now Part 5 takes over.

useLayoutEffect fires synchronously — the DOM is updated, the browser hasn't painted yet. If CartIcon needs to measure its width for an animation, this is the only safe moment. Then the browser paints. She sees the cart count increment.

In the next macro task — after paint, via MessageChannel — useEffect runs. The analytics event fires. localStorage syncs. None of this blocked the paint. None of it delayed what she saw.

What Didn’t Run

Of the entire component tree — dozens of components, hundreds of fibers — exactly three ran their render functions for the cart click:

• The root — has childLanes > 0
• Header — has childLanes > 0
• CartIcon — the state changed here

Everything else: ResultList, SearchInput, Filters, Footer, Recommendations, every ProductCard — skipped. Not because of React.memo. Not because of useCallback. Because childLanes was zero on every other subtree, and React's built-in bailout skipped each one in a single check.

This is the answer to Part 7. The tools exist for the rare cases where the built-in bailout genuinely isn’t enough. For everything else — the default behavior handles it.

The Complete Map

Eight parts. One answer.

Fiber is the foundation. React replaced the opaque JavaScript call stack with its own — plain objects it controls completely. This made pausing, resuming, and prioritizing possible. Without Fiber, nothing else in this series exists.

The Scheduler sits on top of Fiber and decides what runs and when. Keystrokes get SyncLane — they always run first, synchronously. Results renders get TransitionLane — they run in the background, interruptibly. shouldYield() checks the clock after every fiber to keep the browser breathing between frames.

The Reconciler uses the Fiber tree to find the minimum set of DOM changes. It follows the childLanes trail to find what changed, skips everything with clean subtrees, diffs lists by key, and marks flags on fibers — never touching the DOM until the entire decision is made. Then the Commit phase applies everything atomically so the user never sees a half-updated UI.

Algebraic Effects is the mental model that connects Suspense, ErrorBoundary, and hooks. Components signal what they need by throwing. React — acting as the effect handler — catches it, decides what to do, and resumes when the data arrives. useState feels local because of this model, even though state lives on a Fiber node React controls.

Lifecycle is when effects run relative to the Commit phase. useLayoutEffect fires synchronously before the browser paints — for DOM measurements that must happen before the user sees anything. useEffect fires after paint in the next macro task — for everything else. The separation isn't arbitrary. It maps directly to the Commit phase structure.

State is a hook object on a Fiber’s linked list. Calling setState doesn't update immediately — it drops a note in a queue. React reads that queue during the next render, on its own schedule, in its own order. This is why you see the old value after calling setState. The snapshot hasn't changed yet. The note is pending.

Performance is mostly free. The childLanes bailout skips entire subtrees in one check when nothing changed. Structural patterns like children-as-props prevent unnecessary re-renders without any memoization overhead. React.memo, useCallback, and useMemo exist for the small set of cases where the built-in bailout genuinely isn't enough — and they should only be added after measuring.

Server Components moved the question from “how do we render faster on the client” to “how do we send less to the client in the first place.” Server code that never ships. RSC payloads that stream progressively. Selective hydration that prioritizes what the user is interacting with. Every Server Action a public endpoint — treat it like one.

What’s Still Being Built

The series ends here but React doesn’t.

The React Compiler is stable and shipping. It automatically applies the memoization from Part 7 at build time — React.memo, useMemo, useCallback — applied intelligently, without you writing any of it. Understanding this series is exactly what makes your code Compiler-friendly.

use() is the ergonomic layer on top of the algebraic effects model from Part 4. Where Suspense required a data library to implement the throw-Promise pattern, use() exposes it directly from React.

Server Actions security is still maturing. React2Shell revealed a persistent gap between the mental model (local function) and the reality (public HTTP endpoint). The ecosystem is figuring out better defaults. Until then: validate everything.

The One-Sentence Answer

React delivers the best user experience for everyone by giving developers a declarative component model while handling — invisibly — the complexity of prioritizing work, interrupting expensive renders, deferring non-urgent updates, minimizing DOM changes, and progressively delivering content from server to client, through the Fiber and Scheduler machinery built for exactly this purpose.

Eight articles to earn one sentence.

What You Actually Have Now

Before this series, React was a tool you used. After it, React is a system you understand.

The next time an input lags, you know it’s a SyncLane update blocked by a lower-priority render — and you know startTransition is the right fix, not useCallback. The next time a component re-renders unexpectedly, you know to check the reference equality of its props and the childLanes trail — not to wrap everything in React.memo. The next time a page loads slowly, you know the difference between a bundle size problem (Server Components), a data waterfall problem (streaming and Suspense), and a render performance problem (Fiber and Reconciler).

The tools haven’t changed. But the questions you ask before reaching for them have.

That’s what understanding internals actually gives you: not the ability to contribute to React’s source code, but the ability to debug faster, make better decisions earlier, and stop adding complexity to fix problems you only half-understood.

Write something. Ship it. Now you’ll know why it works.

🙏 Thank You

This series exists because of the people who built these systems and took the time to explain them.

Dan Abramov — for Beyond React 16, the Git metaphor that makes Time Slicing click, RSC from Scratch, Algebraic Effects for the Rest of Us, and overreacted.io. More teaching in one career than most people manage in ten.

Andrew Clark — for the react-fiber-architecture document that set the design goals every article in this series built toward.

Sebastian Markbåge — for the algebraic effects mental model that connects Suspense, ErrorBoundary, Hooks, and Context into one coherent story.

Matheus Albuquerque — for the clearest explanation of FiberNode internals at React Summit 2022.

Sam Galson — for connecting React to the wider computer science of fibers, coroutines, and continuations.

JSer (jser.dev) — for the deepest source-level analysis of React internals anywhere on the internet. Every code-level claim in this series was verified against JSer’s work. An extraordinary resource.

Sophie Alpert, Joe Savona, Luna Wei — for the React team’s continued work on documentation, RFCs, and honest discussion of tradeoffs.

Lydia Hallie — for JavaScript visualizations that shaped this series’ style from the beginning.

Lachlan Davidson — for responsibly disclosing CVE-2025–55182 and working with the React team to fix it.

That’s the series. Thank you for reading. 🔧

Tags: #react #javascript #webdev #tutorial

How React Works (Part 9)? The Complete Picture: From a Keystroke to a Pixel was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Series: How React Works Under the Hood Part 1: Motivation Behind React Fiber: Time Slicing & Suspense Part 2: Why React Had to Build Its Own Execution Engine Part 3: How React Finds What Actually Changed Part 4: The Idea That Makes Suspense Possible Part 5: The React Lifecycle From the Inside Part 6: How State Actually Works Part 7: The Trap of Vibe Coding useCallback Prerequisites: Read Parts 1–7 first.

Where We Left Off

Through Parts 1–7, every problem we solved lived on the client. The call stack couldn’t pause — so React built Fiber. Re-rendering was too slow — so React built the Reconciler. State management was confusing — because it’s a queue on a Fiber node, not a variable. Performance tools were overused — because developers reached for them before understanding the problem.

Every solution stayed inside the browser. The user’s device was the bottleneck. The network was just the delivery mechanism.

Part 8 changes that. Because there’s a whole category of problem that no client-side optimization can fix — and it took the React team until 2023 to fully solve it.

The Problem Nobody Talks About

You’ve shipped a React app. You’ve done everything right. You memoized where it mattered. You fixed re-renders. You code-split your routes. React DevTools shows a clean profile. Your API is fast.

Then you open Chrome on a mid-range Android phone with a throttled 3G connection — the kind of device hundreds of millions of people actually use — and you watch the screen stay white for four seconds before anything appears.

You look at the Network tab. Before your user sees a single pixel of your app, their phone downloaded, parsed, and executed 380kb of JavaScript. You open the bundle analyzer. Half of that JavaScript is components that render completely static content — a product description that never changes, a nav with hardcoded links, a footer, a terms page. None of them use state. None of them handle events. They just render text and markup.

But they ship to every client. On every load. On every device. Including that phone on 3G that Part 1 opened with.

This is the problem that Part 1’s question — “with vast differences in computing power and network speed, how do we deliver the best user experience for everyone?” — still hadn’t fully answered by the end of Part 7. We optimized what happens on the client. But we never questioned why so much work was happening on the client in the first place.

The naive fix was server-side rendering. But SSR had a fundamental flaw that took years to properly name — and understanding that flaw is what makes Server Components make sense.

The Problem: The Two-Trip Lie

To understand why Server Components exist, you need to go back to how server rendering worked before them.

Dan Abramov explained the origin story in his RSC from Scratch deep dive by taking you back to 2003. PHP on a server: the server gets a request, reads a file or a database, returns HTML. Simple. The user sees content immediately. No JavaScript bundle to download. No client-side rendering. Just a server doing work and returning a result.

React brought rich interactivity but also a cost: everything runs in the browser. Large bundles. Slow initial loads on slow connections. So the industry added server rendering back — render HTML on the server first, send it to the client, then download JavaScript and “hydrate” the page to make it interactive.

This solved the blank screen problem. But it created what the React team calls a two-trip problem.

The server renders HTML — fast, visible immediately. Then the browser downloads all the JavaScript anyway. React runs again on the client. Re-does the work. Attaches event listeners. Any data fetched on the server to render the HTML? Fetched again on the client. Bundle size? Unchanged — every component that ran on the server also ships to the client. Server work didn’t reduce client work. It looked like a performance win but the full cost came later.

This is the problem Server Components actually solve.

What Hydration Actually Is — and What’s Wrong With It

Server-side rendering gave React apps faster first paint. But it introduced a problem that almost nobody explained clearly: the page looks ready before it is.

The server renders HTML and sends it. The user sees a complete-looking page — the nav, the content, the buttons. They try to click something. Nothing happens. The button doesn’t respond. The form doesn’t submit. The dropdown doesn’t open. The page looks interactive but it isn’t — because React hasn’t attached any event listeners yet.

This is the hydration gap. And it exists because of how hydration works.

From jser.dev’s hydration internals: hydration is not re-rendering. React does not recreate the DOM. Instead, React walks the existing server-rendered DOM tree in parallel with the Fiber tree it’s building, matching each fiber to its corresponding DOM node — storing a reference in fiber.stateNode. Event listeners are attached. The DOM is reused. This is why hydration is faster than a fresh render.

But the entire tree must hydrate before any part becomes interactive. One slow component at the top of the tree blocks the click handlers on a button at the bottom. React walks the tree sequentially, and until that walk is complete, nothing responds.

React 18 fixed this with selective hydration. Using the same Lanes priority system from Part 3, React can now interrupt hydration to handle a user interaction first. If a user clicks a button before hydration reaches it, React jumps to that boundary using SyncLane — hydrates just enough to handle the interaction — then resumes the rest of the tree. The architecture from Part 3 extends directly here: interruptible work, priority-driven, same system.

Streaming takes this further still. Instead of waiting for all data before sending any HTML, the server sends the shell immediately and streams each Suspense boundary as its data resolves. The client starts hydrating what arrived while the rest is still coming. Multiple chunks, progressive — no blank screen waiting for the slowest database query.

But even with selective hydration and streaming, there’s still a cost that SSR never eliminated. The JavaScript still ships. Every component still runs on the client. That’s the problem Server Components solve.

What Server Components Actually Are

From the React Labs March 2023 blog post, written by the React team:

“We are introducing a new kind of component — Server Components — that run ahead of time and are excluded from your JavaScript bundle. Server Components can run during the build, letting you read from the filesystem or fetch static content. They can also run on the server, letting you access your data layer without having to build an API.”

Server Components run only on the server. Their code never ships to the client. Client Components — marked explicitly with 'use client' — run on the client as before. The boundary between them is a decision you make explicitly at every component.

The critical constraint the boundary enforces: functions cannot cross from Server to Client. Functions aren’t serializable. If you try to pass a function as a prop from a Server Component to a Client Component, React throws an error. Only plain serializable values can cross — strings, numbers, objects, arrays, React elements. This shapes every RSC architecture decision. It’s why you can’t pass event handlers from the server side.

What the server sends is not HTML and not JavaScript. It’s the RSC payload — a JSON-like description of the rendered UI tree. Here’s what a simple RSC payload actually looks like in practice:

J0:["$","div",null,{"className":"post"}]
J1:["$","h1",null,{"children":"Hello World"}]
J2:["$","p",null,{"children":"Content here"}]

Each line is a serialized React element — type, key, ref, props. React on the client reads this and builds or updates its Fiber tree from it. As Dan’s RSC from Scratch describes: “a production-ready RSC setup sends JSX chunks as they’re being produced instead of a single large blob at the end. When React loads, hydration can start immediately — React starts traversing the tree using the JSX chunks that are already available.”

For Client Components, only their props get serialized into the payload — not their code, which stays in the bundle. The payload contains a reference to the Client Component (a module ID the bundler knows about) plus the props to render it with.

This is why RSC works with client-side navigation: navigating to a new page in a Next.js App Router app doesn’t reload the whole page. It fetches a new RSC payload and React merges it into the existing Fiber tree — same mechanism, different data.

The React docs explain this model clearly — the boundary rules, how composition works, how to think about what goes where. It’s genuinely good documentation.

What the docs didn’t prepare developers for: the mental model they encourage — writing async function submitOrder() marked 'use server' and calling it like any local function — is exactly the mental model that skips the input validation you'd never skip on an API route. In December 2025, that gap cost real companies their servers.

The Security Reality: React2Shell

On November 29th, 2025, security researcher Lachlan Davidson reported a vulnerability to Meta’s Bug Bounty program. Four days later, the React team disclosed it publicly.

From the official React blog post:

“There is an unauthenticated remote code execution vulnerability in React Server Components.”

CVE-2025–55182 — CVSS 10.0.

The root cause: React Server Functions (Server Actions) allow a client to call a function on the server. React translates the client’s request into an HTTP request, which the server deserializes and executes. The deserialization process did not properly validate inputs. An attacker could craft a malicious HTTP request that, when deserialized by React, achieved remote code execution on the server — with no authentication required, against any app using React Server Components.

The React blog was direct: “Even if your app does not implement any React Server Function endpoints it may still be vulnerable if your app supports React Server Components.”

Exploits appeared within 24 hours of disclosure. Unit 42 at Palo Alto Networks documented post-exploitation activity including reverse shells, malware installation, and activity linked to state-sponsored threat actors.

Two follow-on CVEs were disclosed days later: source code exposure (CVE-2025–55183 — a crafted request could cause the server to return its own source code) and denial of service (CVE-2025–55184 — a crafted request caused an infinite loop that hung the server process permanently). The initial fix for the DoS was incomplete, requiring a second patch under CVE-2025–67779. A fourth vulnerability was disclosed in January 2026 (CVE-2026–23864).

What this means for you as a developer:

Every Server Action ('use server' function) is a public HTTP endpoint. Anyone on the internet can send a POST request to it — not just your frontend. There is no framework magic that makes inputs safe by default. You must validate and sanitize every argument exactly as you would validate input to an Express route handler or an API endpoint.

The mistake RSC encourages is writing server-side logic that feels like an internal function — you’re just calling submitForm() from a button click, it looks local. But it's an HTTP endpoint. Untrusted input. Treat it that way.

Additionally: whatever you pass as props from a Server Component to a Client Component travels in the RSC payload — visible in the browser’s network tab. Pass only what the client needs to render. Passing an entire database row when only a name is needed exposes the rest of that data to anyone watching the network response.

A Concrete Trace: What Actually Happens on Navigation

Let’s make this real. When a user clicks a link in a Next.js App Router app:

User clicks a link. React intercepts the navigation. Instead of a full page reload, it fetches the RSC payload for the new route from the server.

Server processes the request. Server Components for the new route run — async, querying databases, reading files. They render to the RSC payload format. Client Component boundaries are replaced with module references plus serialized props.

Payload streams to the client. The response arrives in chunks. React starts processing chunks as they arrive — it doesn’t wait for the complete response.

React merges the payload into the Fiber tree. For unchanged parts (shared layout, nav), React skips re-rendering entirely. For new content, React creates or updates fibers from the payload. Client Components receive their serialized props and render on the client.

The page updates. No full reload. No loss of client-side state. The URL changes. The content changes. Client Components that were already hydrated stay hydrated.

This is the genuine architectural win: the server does the data work, the client does the interaction work, and the payload is the bridge between them.

The Vibe Coding RSC Trap

In Part 7 we saw what happens when developers add useCallback and React.memo everywhere without measuring — code that's harder to read, harder to debug, and often slower than before.

The same pattern exists with Server Components. You read the Next.js App Router docs. You migrate your pages directory. You follow the examples. And you end up writing code like this:

// Every component that uses state or events gets 'use client'
'use client';
export function Header() { ... }

'use client';
export function SearchInput() { ... }
'use client';
export function ProductCard() { ... }
'use client';
export function Footer() { ... } // doesn't even use state - added just in case

Every component is a Client Component. Every component ships JavaScript to the client. The RSC architecture is in place — the routing, the layout, the page files — but the actual benefit (JavaScript that never ships) is zero. You’ve added the complexity of the Server/Client boundary, the mental overhead of 'use client' everywhere, and the security surface of Server Actions — for a bundle size identical to before.

This happens because the docs show you the mechanics but not the principle. The principle is simple: a component should only be a Client Component if it genuinely needs the client — state, effects, browser APIs, event handlers. Everything else can be a Server Component. A product description that just renders text? Server Component. A nav with static links? Server Component. A footer? Server Component. The question to ask for every component is: does this need to run in the browser?

The vibe coding version asks: does the tutorial mark this as 'use client'? If yes, add it. If the app breaks, add more. This produces an RSC app that costs more than the original — in complexity, in security surface, in developer confusion — and delivers nothing.

When You Don’t Need Server Components

Dan Abramov and Joe Savona discussed the honest tradeoffs of RSC in their live stream with Kent C. Dodds. The team has never claimed RSC is the right tool for every app.

If your app is mostly interactive — drawing tools, real-time editors, complex forms — it consists almost entirely of Client Components anyway. RSC adds architectural complexity for minimal gain. If your API and frontend run in the same region, the round-trip savings from server-side fetching are negligible. The complexity isn’t justified by the performance return.

The more important consideration is team understanding. The React2Shell vulnerability was possible because the boundary between trusted server code and untrusted client input was blurry in the mental model. A team that treats Server Actions as internal functions will skip input validation — and that’s not a performance problem, it’s a critical security bug.

And if you’re adopting RSC because it’s what the new Next.js docs show, stop and ask what problem you’re solving. The React Labs blog post frames RSC as combining the simple request/response model of multi-page apps with the interactivity of single-page apps. That’s a genuine win for content-heavy apps with complex data requirements. For a CRUD app with a fast API and a small bundle, you may be adding architectural weight to solve a problem you don’t have.

Measure the actual loading problem first. Understand the tradeoff. Then decide.

The One-Sentence Rule

Use Server Components when you have a measured loading problem caused by JavaScript bundle size or data waterfalls — and your team treats every Server Action as a public HTTP endpoint that requires the same validation discipline as any API route. In every other case, measure the problem first.

What’s Coming in Part 9

Part 9 is the last article in the series. It answers the question Part 1 opened with: “With vast differences in computing power and network speed, how do we deliver the best user experience for everyone?” — pulling every piece of the series together into one complete picture.

🎬 Watch These

Dan Abramov — RSC from Scratch (GitHub Discussion) The canonical technical deep dive — inventing RSC from first principles. The RSC payload format and the streaming architecture described in this article come directly from this document.

Dan Abramov + Joe Savona — RSC Live Stream with Kent C. Dodds Honest discussion of RSC tradeoffs, limitations, and the mental model shift required. The source for the “when you don’t need RSC” framing.

JSer (jser.dev) — How basic hydration works internally in React? The tryToClaimNextHydratableInstance, fiber.stateNode matching, and cursor-based DOM walking described in this article.

JSer (jser.dev) — What is Progressive Hydration and how does it work internally? Streaming HTML in chunks, Suspense comment node markers (<!--$-->, <!--$!-->), and the retry callback mechanism.

🙏 Sources & Thanks

• Dan Abramov — RSC from Scratch (Part 1) written by @gaearon on the reactwg GitHub. The PHP origin story, the RSC payload format, the streaming architecture, and the quote about JSX chunks all come directly from this document.
• The React Team — React Labs: March 2023 — the official Server Components definition quoted directly. Critical Security Vulnerability in React Server Components — the official React2Shell disclosure, the vulnerability overview, and the timeline all come from the react.dev blog post.
• Lachlan Davidson — for discovering and responsibly reporting CVE-2025–55182 to Meta’s Bug Bounty program.
• jser.dev — the hydration mechanics (tryToClaimNextHydratableInstance, nextHydratableInstance cursor, fiber-to-DOM matching, selective hydration with Lanes priority, streaming with comment node markers) all come from JSer's source-level analysis: How basic hydration works, How hydration works with Suspense, What is Progressive Hydration, and My guess at how RSC works.
• Unit 42 / Palo Alto Networks — for the post-exploitation analysis of CVE-2025–55182 documenting real-world attack patterns.
• Dan Abramov + Joe Savona — RSC Live Stream with Kent C. Dodds — for the honest discussion of RSC tradeoffs that informed the “when you don’t need it” section.

Part 9 is the final article — the full picture, from Part 1’s question to the complete answer. 🔧

Tags: #react #javascript #webdev #tutorial #security

How React Works (Part 8)? Server Components & Hydration: The Real Story was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Series: How React Works Under the Hood Part 1: Motivation Behind React Fiber: Time Slicing & Suspense Part 2: Why React Had to Build Its Own Execution Engine Part 3: How React Finds What Actually Changed Part 4: The Idea That Makes Suspense Possible Part 5: The React Lifecycle From the Inside Part 6: How State Actually Works Prerequisites: Read Parts 1–6 first — especially Parts 3 and 6.

🚀 Land Your Dream Tech Job in Just Weeks

💰 $50–$120/hr | Multiple Roles Open
Frontend • Backend • Full Stack • AI/ML • DevOps

👉 Apply Now & Get Hired Faster

Where We Left Off

In Part 6 we saw how useState works — state stored on the Fiber as a hook object, updates queued and processed on the next render, the component function running fresh from the top every time. Every render. From the top.

That last part is what this article is about. Because every render from the top means every value inside the component is recreated. And that single fact is the root cause of most React performance problems — and the reason the most common advice for fixing them often makes things worse.

You Wrapped Everything in useCallback. You Added React.memo to Every Component. Your App Is Still Slow. What Went Wrong?

This is the scene. You open the React DevTools Profiler. Components are re-rendering on every interaction. You’ve read the articles. You know the tools. So you do what everyone does:

function SearchPage() {
  const [query, setQuery] = useState('');
  const [filters, setFilters] = useState({});

  const handleSearch = useCallback(() => search(query), [query]);
    const handleFilter = useCallback((key, val) => setFilters(f => ({...f, [key]: val})), []);
    const handleReset = useCallback(() => setFilters({}), []);
    const handleExport = useCallback(() => exportResults(query, filters), [query, filters]);
    const activeFilters = useMemo(
      () => Object.entries(filters).filter(([_, v]) => v),
      [filters]
    );
    return (
      <ResultList
        onSearch={handleSearch}
        onFilter={handleFilter}
        onReset={handleReset}
        onExport={handleExport}
        activeFilters={activeFilters}
      />
    );
  }

  const ResultList = React.memo(({ onSearch, onFilter, onReset, onExport, activeFilters }) => {
    // ...
  });

You deploy. You open the Profiler again. ResultList is still re-rendering. Some interactions are slower than before.

What went wrong?

This article answers that — from the inside out.

React’s Default: Re-render Everything, Skip What It Can

React’s mental model has always been simple: when state changes, re-render. Not just the component that changed — all of its children too.

But React has a built-in bailout system we covered in Part 3. When React walks down to a child, it checks one thing before running it:

Are the props the same object reference as last render?

If yes — same reference, not just same values — React skips that component entirely. The child doesn’t run. Its children don’t run. The entire subtree is skipped in one check. Free, automatic, no tools required.

The problem: in practice, props almost always get new references on every render — even when the values inside them are identical. And this is the root cause of most React performance problems.

Every Render Creates New References Without You Noticing

When a parent component re-renders, it runs its function from the top. Every line executes again:

function SearchPage() {
  const [query, setQuery] = useState('');

  // ❌ New function object on every render
  const handleSearch = () => search(query);
  // ❌ New object on every render
  const style = { color: 'red', padding: '8px' };
  // ❌ New array on every render
  const results = data.filter(item => item.active);
  return <ResultList onSearch={handleSearch} style={style} results={results} />;
}

Every render, handleSearch is a brand new function. style is a brand new object. results is a brand new array. They look identical — same values, same contents — but they're different objects in memory.

React’s bailout uses === reference equality. Old handleSearch !== new handleSearch. So React can't bail out, and ResultList re-renders on every keystroke in the search input — even when the results haven't changed.

The Part Nobody Tells You: Children Re-render Even With No Props

Here’s the insight that most performance guides miss entirely.

Given this structure:

function SearchPage() {
  const [query, setQuery] = useState('');

return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <ResultList />  {/* no props at all */}
    </div>
  );
}

When the user types and SearchPage re-renders, ResultList re-renders too — even though it receives zero props.

Why? Because when SearchPage's function runs, it creates a new React element for <ResultList />. That element object is new. When React's reconciler compares the old pendingProps to the new pendingProps on the ResultList fiber, they're different objects. So React re-renders ResultList. The issue isn't the prop values — it's where the element is created.

This means React.memo on ResultList alone doesn't help here at all.

The Free Fix: Children as Props

This is the most underused performance pattern in React. Zero memoization. Zero dependency arrays. Just a structural change.

// ❌ Before — ResultList re-renders whenever SearchPage re-renders
function SearchPage() {
  const [query, setQuery] = useState('');
  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <ResultList />
    </div>
  );
}

// ✅ After - ResultList never re-renders when query changes
function App() {
  return (
    <SearchPage>
      <ResultList />
    </SearchPage>
  );
}
function SearchPage({ children }) {
  const [query, setQuery] = useState('');
  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      {children}
    </div>
  );
}

function SearchPage({ children }) {
  const [query, setQuery] = useState('');
  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      {children}
    </div>
  );
}

Why does this work? The <ResultList /> element is now created inside App, not inside SearchPage. When SearchPage's state changes, App doesn't re-render. The children prop that SearchPage receives is the same object reference as before. React's built-in bailout kicks in — same reference, skip ResultList.

No React.memo. No useCallback. No overhead. Just structure.

The React docs state this directly: “When a component visually wraps other components, let it accept JSX as children. This way, when the wrapper component updates its own state, React knows that its children don’t need to re-render.”

Always try structural fixes before reaching for memoization tools. They’re free and they don’t break.

When You Actually Need React.memo

Sometimes the structural fix isn’t possible. The child genuinely needs to be defined inside the parent and receive real props. That’s when React.memo enters.

React.memo wraps your component in a MemoComponent fiber. Instead of checking reference equality on the whole props object, React runs shallowEqual — comparing each individual prop value:

const ResultList = React.memo(({ results, onSearch }) => {
  return <div>{results.map(r => <Result key={r.id} data={r} />)}</div>;
});

If results and onSearch have the same values as last time, React bails out. Even if the props object itself is new.

One internal detail worth knowing: when you wrap a simple function component with no custom compare function and no defaultProps, React silently upgrades the fiber tag from MemoComponent to SimpleMemoComponent — a faster internal optimization path. Add a custom compare function and you lose this fast path.

But React.memo alone almost never works. If any prop is a function or object created inline during render, shallowEqual fails on that prop — new reference every time. React.memo bails out on nothing.

This is why in the opening example, ResultList still re-renders even though it's wrapped in React.memo. handleSearch, handleFilter, handleReset, handleExport — all created inline, all new references every render. React.memo sees four changed props and re-renders anyway.

What useCallback and useMemo Actually Do — From the Source

useCallback and useMemo exist for one reason: to stabilize references so React.memo can do its job.

Here’s the actual source code for both hooks — mountMemo on initial render and updateMemo on re-render:

// From React source — initial render
function mountMemo(nextCreate, deps) {
  const hook = mountWorkInProgressHook(); // create hook in linked list
  const nextDeps = deps === undefined ? null : deps;
  const nextValue = nextCreate();          // run the factory fn
  hook.memoizedState = [nextValue, nextDeps]; // store [value, deps]
  return nextValue;
}

// From React source - every re-render
function updateMemo(nextCreate, deps) {
  const hook = updateWorkInProgressHook(); // walk to this hook in linked list
  const nextDeps = deps === undefined ? null : deps;
  const prevState = hook.memoizedState;   // [prevValue, prevDeps]
  if (prevState !== null && nextDeps !== null) {
    const prevDeps = prevState[1];
    if (areHookInputsEqual(nextDeps, prevDeps)) {
      return prevState[0];               // deps unchanged → return cached value
    }
  }
  const nextValue = nextCreate();         // deps changed → recompute
  hook.memoizedState = [nextValue, nextDeps];
  return nextValue;
}

updateCallback is identical — the only difference is it stores the function itself instead of calling it.

The dependency comparison runs through areHookInputsEqual:

// From React source — runs on every render for every hook
function areHookInputsEqual(nextDeps, prevDeps) {
  for (let i = 0; i < prevDeps.length && i < nextDeps.length; i++) {
    if (Object.is(nextDeps[i], prevDeps[i])) {
      continue;
    }
    return false; // one mismatch → recompute
  }
  return true;
}

This loop runs on every render, for every hook, for every dependency. It doesn’t matter whether deps changed or not — the loop always runs.

The Hidden Cost: What Happens on Every Render

This is what the articles don’t tell you.

Even when dependencies haven’t changed and useCallback/useMemo return the cached value, React still does this on every render:

1. Walks to this hook in the linked list — updateWorkInProgressHook() traverses the hook chain every time
2. Reads hook.memoizedState — accesses [prevValue, prevDeps] from memory
3. Runs areHookInputsEqual — loops through every dependency with Object.is
4. Allocates a new function (for useCallback) — React receives the new () => fn you wrote, then decides whether to discard it

That last point surprises most developers. When you write:

const handleSearch = useCallback(() => search(query), [query]);

JavaScript creates the arrow function () => search(query) before calling useCallback. React receives it, runs areHookInputsEqual, and if deps haven't changed, discards the new function and returns the old one. The allocation happened regardless.

So useCallback(fn, [a, b, c]) with unchanged deps on every render means: one function allocation (discarded), three Object.is comparisons, one linked list traversal. For a component that re-renders 50 times per second during a scroll, that's 150 comparisons per second — for a component that might have been fast to render in 0.1ms anyway.

The Vibe Coding Trap

Here’s what actually happens in most codebases.

Someone reads that useCallback prevents re-renders. They add it to every function. They add React.memo to every component. They add useMemo to every derived value. "Just to be safe." Copy-paste from the last project. Vibe coding.

// Real pattern from real codebases
function ProfileCard({ userId }) {
  const handleMouseEnter = useCallback(() => setHovered(true), []);
  const handleMouseLeave = useCallback(() => setHovered(false), []);
  const handleFocus = useCallback(() => setFocused(true), []);
  const handleBlur = useCallback(() => setFocused(false), []);
  const containerClass = useMemo(
    () => `card ${hovered ? 'card--hovered' : ''} ${focused ? 'card--focused' : ''}`,
    [hovered, focused]
  );

return (
    <div
      className={containerClass}
      onMouseEnter={handleMouseEnter}
      onMouseLeave={handleMouseLeave}
      onFocus={handleFocus}
      onBlur={handleBlur}
    >
      <UserAvatar userId={userId} />
    </div>
  );
}

This is a card component. It renders in under 0.1ms. Nothing inside it is expensive. UserAvatar doesn't receive any of the memoized values. The containerClass string is trivially fast to compute.

Every single useCallback and useMemo here adds overhead — dependency comparisons, hook traversals, function allocations — for zero performance benefit. The component was never the bottleneck.

And the real cost shows up in debugging. When containerClass produces the wrong value, you now have to trace through useMemo and its [hovered, focused] deps to understand why. When handleFocus behaves unexpectedly, you check the useCallback closure. What was a simple state bug becomes a memoization debugging session.

The React docs are direct about this: “There is no significant harm to doing that either, so some teams choose to not think about individual cases, and memoize as much as possible. The downside of this approach is that code becomes less readable. Also, not all memoization is effective: a single value that’s ‘always new’ is enough to break memoization for an entire component.”

The Right Order

Here’s the order that actually fixes performance problems:

1. Measure first. Open React DevTools Profiler. Record a session. Find the component that’s actually slow — its render time, how often it renders, and why. Don’t optimize what you haven’t measured. Most of the time the bottleneck is not where you think it is.

2. Fix the structure. Can the slow child’s element be created in a parent that doesn’t re-render? Can state be moved down closer to where it’s used? Can you use the children-as-props pattern? These fixes are free — no memoization overhead, no stale closure risk, no dependency arrays to maintain.

3. Memoize if structure can’t fix it. If structural fixes aren’t possible and the component is genuinely expensive to render and receives props that could be stable — then reach for React.memo + useCallback/useMemo together. All three are needed. React.memo without stable references does nothing. useCallback without React.memo on the child does nothing.

4. Verify it worked. Re-run the Profiler. Confirm the component no longer re-renders unnecessarily. If it still does, find what reference is still unstable and trace it back.

The rule, in one sentence: don’t add memoization until you have a specific, measured component that re-renders too often, with expensive renders, and props that can be stabilized.

A Note on the React Compiler

The React Compiler (previously React Forget) is now stable. It’s a build-time Babel plugin that automatically applies memoization where it’s safe — analyzing your components, inferring dependencies, and inserting optimizations without you writing any of it.

But it only works on components that follow the Rules of React: pure renders, no prop mutation, no non-deterministic values during render. Code that follows these rules gets automatic optimization. Code that doesn’t gets de-opted — the Compiler falls back and does nothing.

Here’s the important point: understanding everything in this article — why references matter, why structural fixes come first, why useCallback has a cost — is exactly what you need to write code the Compiler can optimize. The Compiler doesn't replace understanding React's rendering model. It rewards you for having it.

What’s Coming in Part 8

In Part 8 we go into Server Components and Hydration — how React renders on the server, streams the result to the client, and hands off interactivity without re-doing all the work. The rendering model we’ve built throughout this series extends to the server in some surprising ways.

🎬 Watch These

JSer (jser.dev) — How does React bailout work in reconciliation? The source for the “children re-render even with no props” insight and the children-as-props bailout pattern. The demo shows exactly which components re-render and why.

JSer (jser.dev) — How does React.memo() work internally? The MemoComponent vs SimpleMemoComponent internal distinction and shallowEqual — the source for the React.memo internals section.

🙏 Sources & Thanks

• jser.dev — the “children re-render even with no props” insight and the children-as-props bailout technique come directly from How does React bailout work?. The MemoComponent/SimpleMemoComponent distinction from How does React.memo() work internally?
• React source — mountMemo, updateMemo, mountCallback, updateCallback, and areHookInputsEqual are taken directly from packages/react-reconciler/src/ReactFiberHooks.js in the facebook/react repo. Verified via multiple source walkthroughs.
• React docs — the children-as-props principle and the “not all memoization is effective” quote come directly from react.dev/reference/react/memo. The React Compiler section draws from react.dev/learn/react-compiler.
• Lydia Hallie — for JavaScript visualizations that shaped this series’ style.

Part 8 is next — Server Components and Hydration: how React moved rendering to the server without breaking the client model. 🔧

Tags: #react #javascript #webdev #performance #tutorial

Thank you for being a part of the community

Before you go:

👉 Be sure to clap and follow the writer ️👏️️

👉 Follow us: Linkedin| Medium

👉 CodeToDeploy Tech Community is live on Discord — Join now!

Disclosure: This post includes affiliate and partnership links.

How React Works (Part 7)? The Trap of Vibe Coding `useCallback` was originally published in CodeToDeploy on Medium, where people are continuing the conversation by highlighting and responding to this story.

Series: How React Works Under the Hood Part 1: Motivation Behind React Fiber: Time Slicing & Suspense Part 2: Why React Had to Build Its Own Execution Engine Part 3: How React Finds What Actually Changed Part 4: The Idea That Makes Suspense Possible Part 5: The React Lifecycle From the Inside Prerequisites: Read Parts 1–5 first.

Three Things That Confuse Almost Everyone

Here are three behaviors of useState that trip up developers at every level:

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

  function handleClick() {
      setCount(count + 1);
      setCount(count + 1);
      setCount(count + 1);
      // You might expect count to become 3
      // It becomes 1
    }

    function handleLog() {
      setCount(count + 1);
      console.log(count);
      // You might expect to see the new value
      // You see the old value
    }

    function handleSame() {
      setCount(count); // setting same value
      // You might expect no re-render
      // Sometimes React still re-renders once
    }
}

All three behaviors make complete sense once you understand how useState actually works under the hood. This article explains all three — and by the end, you'll never be surprised by state again.

Where State Lives

The most important question to start with: when you call useState(0), where does that 0 actually live?

Not in the component function. Component functions are just regular JavaScript functions — they have no persistent memory between calls. Every time React re-renders your component, it calls the function fresh from the top.

State lives on the Fiber. Specifically, on a hook object stored in the fiber’s memoizedState field.

Every hook call creates a new hook object and appends it to a linked list hanging off the fiber:

Counter fiber
  └─ memoizedState → hook (useState count)
                       └─ next → hook (useEffect)
                                   └─ next → hook (useRef)
                                               └─ next → null

Each hook object stores the current state value in its own memoizedState field, plus an updateQueue for pending updates, plus a link to the next hook.

This is why the rules of hooks exist — specifically why you can’t call hooks conditionally. React doesn’t track hooks by name. It tracks them by position in the linked list. Call number 1 is always useState count, call number 2 is always useEffect, and so on. If you skip a hook call with an if statement, every subsequent hook gets the wrong state from the wrong position.

What Happens When You Call setState

Here’s what most developers picture when they call setCount(count + 1):

React updates the count, then re-renders the component.

Here’s what actually happens:

React creates a small update object and adds it to a queue. Then it schedules a re-render for later. The component function does not run again right now.

That’s it. Calling setState is not synchronous. It's not instant. It's closer to leaving a note — "please re-render this component with this new value when you get a chance."

Here is the actual sequence:

Step 1 — Create an update object. React packages your new value (or updater function) into a small object that also carries the current priority lane.

Step 2 — Stash it in a queue. The update goes into a global buffer (concurrentQueues). It's not attached to the fiber yet — React is potentially in the middle of rendering something else and can't safely modify the fiber tree right now.

Step 3 — Schedule a re-render. React calls scheduleUpdateOnFiber, which walks up to the root, marks the trail of childLanes, and registers a task with the Scheduler (from Part 2). The Scheduler will call back to run the render.

Step 4 — At the start of the next render, attach updates. Before the render begins, finishQueueingConcurrentUpdates runs and attaches all stashed updates from the global buffer to their respective fibers' queues. Now the fiber is ready to process them.

Step 5 — During render, process the queue. When React processes the Counter fiber, it reads hook.queue, processes the pending updates in order, and the result becomes the new hook.memoizedState — the new value that useState will return for this render.

A Concrete Trace: One Button Click

Let’s make this real. The Counter from the opening — count starts at 0, user clicks the button:

The click happens. The browser fires a click event. React’s synthetic event handler calls your handleClick, which calls setCount(count + 1) — that's setCount(1).

dispatchSetState runs. React creates an update object { action: 1, lane: SyncLane } and pushes it into the global concurrentQueues buffer. The Counter fiber is unchanged — it still has hook.memoizedState = 0. The component function has not run again yet.

scheduleUpdateOnFiber runs. React walks up from the Counter fiber to the root, marking childLanes on every ancestor. The Scheduler registers a task to call performConcurrentWorkOnRoot.

The event handler finishes. React checks for other queued updates — there are none. Since this was a user interaction (SyncLane), React runs the render synchronously rather than waiting for the next macro task.

finishQueueingConcurrentUpdates runs. The pending update is moved from the global buffer and attached to hook.queue.pending on the Counter fiber. The fiber is now ready.

React renders the Counter fiber. updateState reads hook.queue, finds the pending update { action: 1 }, runs it through basicStateReducer, and gets 1. This becomes the new hook.memoizedState. The component function runs with count = 1 and returns new JSX.

Commit phase. React finds the changed text node and updates button.textContent to "click 1". The DOM reflects the new state.

Total time from click to DOM update: a few milliseconds. Total re-renders: exactly one.

Why You See the Old Value After setState

Now the first confusion makes sense.

setCount(count + 1);
console.log(count); // still the old value

Calling setCount didn't change count. It created an update object and scheduled a re-render. The variable count is a local variable in the current function call — it was captured when the component rendered and it will never change during this render. The new value only exists after the next render completes and useState reads from the processed queue.

This is a fundamental property of React’s model: state values are snapshots. Every render captures its own version of state, and that snapshot is frozen for the duration of that render.

Why Three setCount Calls Only Increment Once

setCount(count + 1);
setCount(count + 1);
setCount(count + 1);
// count goes from 0 to 1, not 0 to 3

Each of these three calls captures the same count — the snapshot from the current render, which is 0. So all three are equivalent to setCount(0 + 1). React queues three updates, all with value 1. When it processes them in the next render, the result is 1.

The fix is the updater function form:

setCount(c => c + 1);
setCount(c => c + 1);
setCount(c => c + 1);
// count goes from 0 to 3

When you pass a function, React processes the updates in sequence — each one receives the result of the previous. The queue runs 0 → 1 → 2 → 3. The updater function form is specifically designed for when you need to chain updates.

Why Multiple setState Calls Don't Cause Multiple Re-renders

This is batching — and it’s one of React’s most important performance features.

When you call setState multiple times in the same event handler, React doesn't re-render after each call. It collects all the updates, then does a single re-render at the end.

function handleClick() {
  setCount(c => c + 1);  // queued
  setName('Alice');       // queued
  setLoading(false);      // queued
  // → one re-render, not three
}

Updates are stashed in the global concurrentQueues buffer and only attached to fibers at the beginning of the next render via finishQueueingConcurrentUpdates. This means all three setState calls during the same event handler land in the queue before any render begins — React processes them all in one pass.

Before React 18, batching only happened inside React event handlers. In setTimeout, fetch callbacks, or native event handlers, each setState would trigger a separate re-render. React 18 introduced automatic batching — batching now happens everywhere by default, regardless of where the update originates.

The Same-Value Optimization (and Its Catch)

What happens when you call setState with the same value the state already has?

setCount(count); // count is already 5, setting it to 5 again

React tries to skip the re-render entirely. Before scheduling the re-render, dispatchSetState eagerly computes the new state and compares it to the current state using Object.is. If they're identical, React calls enqueueConcurrentHookUpdateAndEagerlyBailout and returns immediately — no render is scheduled.

But here’s the catch: this bailout only happens when the fiber’s update queue is currently empty. If there’s other pending work on the component, React can’t safely apply this optimization and may still re-render once. The comment in the React source code says “React tries to avoid scheduling re-render with best effort, but no guarantee.”

So the rule in practice: setting state to the same value usually prevents a re-render, but not always. Don’t write code that depends on this optimization for correctness.

useRef: State Without Re-renders

Now that you understand how useState works, useRef becomes obvious.

useRef is implemented almost identically to useState — it creates a hook object on the fiber's linked list, stores its value in memoizedState. The difference: updating a ref doesn't create an update object and doesn't call scheduleUpdateOnFiber. It just mutates the current property of the ref object directly.

const ref = useRef(0);
ref.current = 1; // direct mutation — no queue, no schedule, no re-render

Because React never learns about the change, it never re-renders. The new value is available immediately (no snapshot problem), but React won’t react to it. This makes useRef perfect for values that need to persist across renders without triggering them — timer IDs, previous values, DOM node references.

The tradeoff is exactly what you’d expect: refs are live, mutable, immediate — but invisible to React’s rendering system.

The Full Picture

useState is not a magical React primitive. It's a hook object on a linked list on a fiber, with a queue for pending updates and a scheduler that processes them. Every behavior that seems surprising becomes logical once you see the structure:

The snapshot problem exists because state is stored on the fiber, not in a mutable variable — and the fiber gets its new value only after the render processes the queue. The batching behavior exists because updates go into a global buffer before being attached to fibers. The same-value optimization exists because React checks eagerly before scheduling. And useRef is simply the same structure without the scheduling step.

State in React is not instant, synchronous, or mutable in the traditional sense. It’s a description of what the next render should look like — and React processes that description on its own schedule, in its own order, using the Fiber and Scheduler machinery from Parts 2 and 3.

What’s Coming in Part 7

In Part 7 we look at performance — not the solutions first, but the problems. What actually causes unnecessary re-renders? Why does passing a new object as a prop matter? When is React doing work it doesn’t need to? Understanding the problems clearly is what makes React.memo, useMemo, and useCallback make sense — rather than things you add until the lag goes away.

🎬 Watch These

JSer (jser.dev) — How does useState() work internally in React? The primary source for this entire article — mountState, dispatchSetState, concurrentQueues, finishQueueingConcurrentUpdates, the eager bailout, and the batching mechanism. All sourced from here.

JSer (jser.dev) — How does React re-render internally? How the update queue is processed during the render phase — the other half of the state story.

🙏 Sources & Thanks

• jser.dev — every mechanism in this article comes from JSer’s source-level analysis of useState. The mountState flow, dispatchSetState internals, concurrentQueues global buffer, finishQueueingConcurrentUpdates, the eager same-value bailout with the "best effort, no guarantee" caveat, and the batching explanation all come directly from How does useState() work internally in React?
• React source — packages/react-reconciler/src/ReactFiberHooks.js (mountState, dispatchSetState, mountWorkInProgressHook) and packages/react-reconciler/src/ReactFiberConcurrentUpdates.js (enqueueConcurrentHookUpdate, finishQueueingConcurrentUpdates) in the facebook/react repo.
• Lydia Hallie — for JavaScript visualizations that shaped this series’ style.

Part 7 is next — performance: what actually causes unnecessary re-renders, before we reach for any optimization tools. 🔧

Tags: #react #javascript #webdev #tutorial

How React Works (Part 6)? How State Actually Works: useState from the Inside was originally published in JavaScript in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.

Series: How React Works Under the Hood Part 1: Motivation Behind React Fiber: Time Slicing & Suspense Part 2: Why React Had to Build Its Own Execution Engine Part 3: How React Finds What Actually Changed Part 4: The Idea That Makes Suspense Possible Prerequisites: Read Parts 1–4 first.

A Puzzle Most React Developers Get Wrong

Quick quiz. What order do these log?

function App() {
  useLayoutEffect(() => {
    console.log('layout effect');
  });

  useEffect(() => {
    console.log('effect');
  });

  console.log('render');
  return <div />;
}

Most people guess: render → effect → layout effect, or render → layout effect → effect.

The answer is: render → layout effect → effect.

But more importantly — why? Why does useLayoutEffect run before useEffect? Why does useEffect run at all after the component already returned? What does "after the browser paints" actually mean, and is that even always true?

This article answers all of that. And by the end, you’ll be able to look at any component and predict exactly when each piece of it runs — and why.

The Three Phases of a React Render

Before we get into effects, we need to remember the pipeline from Part 2. Every React update goes through three phases:

Render — React runs your component functions, diffs the trees, figures out what changed. Nothing is written to the DOM yet. This is where console.log('render') fires.

Commit — React takes everything it figured out during Render and applies it to the real DOM. This is synchronous and uninterruptible.

Effects — After the DOM is updated, React runs your effects.

The key insight is that effects are not part of rendering. They’re a separate step that happens after the DOM is already updated. This is why you can safely read the DOM inside an effect — by the time it runs, the DOM reflects the current state.

What useEffect Actually Is

Here’s the mental model most developers have: useEffect is "code that runs after render." That's roughly right but missing the important details.

Here’s the more accurate model: useEffect is a declaration that you have side effects to run after React is done with the DOM. You're not scheduling a callback — you're telling React about work that needs to happen, and React decides when to run it.

The distinction matters because React doesn’t run effects immediately after commit. It schedules them.

After the Commit phase finishes updating the DOM, React schedules your useEffect callbacks as a separate task in the Scheduler's queue — the same Scheduler we covered in Part 2. That means effects run in a new macro task, after the browser has had a chance to paint the updated screen.

This is why the React docs say useEffect runs "after the browser paints." The sequence looks like this:

1. Render phase — your component functions run
2. Commit phase — DOM is updated
3. Browser paints the screen
4. Scheduler fires — useEffect callbacks run

The browser gets step 3 because steps 1–2 are one macro task, and step 4 is a new macro task. Between any two macro tasks, the browser can paint.

The Cleanup: Why It Runs Before the Next Effect

Every useEffect can return a cleanup function:

useEffect(() => {
  const subscription = subscribe(id);
  return () => subscription.unsubscribe(); // cleanup
}, [id]);

When id changes and the effect needs to re-run, React runs the cleanup of the previous effect first, then runs the new effect. Always in that order.

This is also true on unmount — the cleanup runs when the component leaves the tree.

The reason is straightforward: React never wants two instances of the same effect active at the same time. Before setting up the new subscription, it tears down the old one. This is React being deliberate about side effects — always clean up before you set up again.

Cleanups run first in commitPassiveUnmountEffects, then new effects run in commitPassiveMountEffects. Both happen in the same scheduled task, in the same order as the tree (children before parents, same as completeWork).

useLayoutEffect: The Synchronous Version

Here’s the critical difference: useLayoutEffect runs synchronously inside the Commit phase, before the browser paints.

The sequence with useLayoutEffect:

1. Render phase — component functions run
2. Commit phase — DOM is updated
3. useLayoutEffect callbacks run  ← here, synchronously, before paint
4. Browser paints
5. useEffect callbacks run        ← here, in next macro task

This is why useLayoutEffect fires before useEffect in our opening quiz — it's not "earlier in the same phase," it's in a completely different phase.

And this is why useLayoutEffect exists at all. If you need to read the DOM after it's updated but before the user sees it — for example, measuring an element's size to position a tooltip — useLayoutEffect is the only place where that's safe and accurate.

// useLayoutEffect — correct for DOM measurements
useLayoutEffect(() => {
  const rect = ref.current.getBoundingClientRect();
  setTooltipPosition({ top: rect.bottom, left: rect.left });
});


// useEffect - would cause a visible flicker for measurements
// because the browser already painted before this runs
useEffect(() => {
  const rect = ref.current.getBoundingClientRect();
  setTooltipPosition({ top: rect.bottom, left: rect.left }); // too late
});

If you use useEffect for a DOM measurement that affects layout, the user will briefly see the wrong layout (before useEffect runs), then see it jump to the correct layout (after). That flicker is exactly what useLayoutEffect prevents.

The “After Paint” Rule Has an Exception

Here’s something that React’s own documentation gets wrong.

The docs say useEffect always runs after the browser paints. But that's not strictly true.

Sometimes React runs useEffect callbacks before paint. This happens when React determines it's more important to show the latest UI as quickly as possible — for example, when a re-render is triggered by a user interaction, or when effects are scheduled under layout effects. In those cases, React won't wait for a paint before running the effects.

From jser.dev’s paint timing analysis:

“I’d explain the timing of running useEffect() callbacks as follows. useEffect() callbacks are run after DOM mutation is done. Most of the time, they are run asynchronously after paint, but React might run them synchronously before paint when it is more important to show the latest UI — for example when re-render is caused by user interactions or scheduled under layout effects, or simply if React has the time internally to do so.”

The practical implication: never rely on useEffect to run after paint for correctness. If your code requires running after the browser paints, useLayoutEffect with its explicit synchronous-before-paint guarantee is actually the more predictable choice. And if you truly need to run something after paint for non-DOM reasons, the gap is usually small enough not to matter.

The Dependency Array: What It Actually Controls

The dependency array in useEffect and useLayoutEffect doesn't control whether the effect runs — it controls when it re-runs.

React compares the current values of the dependency array to the previous ones using Object.is (similar to === but handles NaN and -0 correctly). If any value changed, React marks the effect with a flag indicating it should run again. If nothing changed, the effect is skipped this cycle.

useEffect(() => {
  fetchUser(id);
}, [id]); // only re-runs when id changes

Three cases:

No dependency array — re-runs after every render. The effect has no conditions.

Empty array [] — runs once on mount, cleanup runs on unmount. Effect has no dependencies that can change.

Array with values — re-runs whenever any listed value changes between renders.

The important thing to understand: React doesn’t track what you use inside the effect. It trusts the dependency array you provide. If you use userId inside the effect but forget to put it in the array, React won't re-run the effect when userId changes — and you get a stale value bug. This is why eslint-plugin-react-hooks exists: it statically analyzes your effect and warns when the array is incomplete.

The Full Lifecycle in One Timeline

The pattern is consistent across every scenario. On mount, the component renders, React commits the DOM, useLayoutEffect fires synchronously before the browser paints, the browser paints, then useEffect runs in the next macro task. On update, cleanups always run before new effects — layout cleanup first, then layout create, then paint, then passive cleanup, then passive create. On unmount, both cleanups run in the same order, layout before passive, with paint in between.

Two things are always true regardless of the scenario: layout effects are synchronous and pre-paint, passive effects are scheduled and post-commit. And cleanups always run before the next effect of the same type — React never has two instances of the same effect active at once.

When to Use Which

Use useEffect for everything by default. Most side effects — data fetching, subscriptions, logging, timers — don't need to happen before the browser paints. Running them after paint keeps the UI responsive and is the right choice in the vast majority of cases.

Reach for useLayoutEffect only when you need to read or modify the DOM before the user sees it — measuring element dimensions, positioning a tooltip relative to another element, or preventing a visual flicker. The practical test is simple: if swapping useLayoutEffect for useEffect causes a visible jump or flash in the UI, you needed useLayoutEffect. If it looks identical, stick with useEffect.

What’s Coming in Part 6

In Part 6 we go inside useState — how state is stored on the Fiber, what happens when you call setState, and why calling setState multiple times in one event handler doesn't cause multiple re-renders.

🎬 Watch These

JSer (jser.dev) — The lifecycle of effect hooks in React The source for the Effect object internals, HookHasEffect tag, flushPassiveEffects, and cleanup ordering in this article.

JSer (jser.dev) — How does useLayoutEffect() work internally? The synchronous commit-phase timing of layout effects vs passive effects — the source for the timing difference explained here.

JSer (jser.dev) — When do useEffect() callbacks get run? Before paint or after paint? The surprising finding that React.dev’s “always after paint” description is inaccurate — and the real timing rules.

🙏 Sources & Thanks

• jser.dev — all timing mechanics in this article come from JSer’s source-level analysis. Articles used: The lifecycle of effect hooks in React, How does useLayoutEffect() work internally?, How does useEffect() work internally in React?, and When do useEffect() callbacks get run? — including the quote about React.dev’s inaccurate description.
• React source — ReactFiberCommitWork.js (commitLayoutEffects, commitPassiveMountEffects, commitPassiveUnmountEffects) and ReactFiberWorkLoop.js (scheduleCallback for passive effects).
• Lydia Hallie — for JavaScript visualizations that shaped this series’ style.

Part 6 is next — how useState actually works: where state lives, what happens when you call setState, and why multiple calls in one handler don't cause multiple re-renders. 🔧

Tags: #react #javascript #webdev #tutorial

How React Works (Part 5)? The React Lifecycle From the Inside: When Things Actually Run was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Series: How React Works Under the Hood Part 1: Motivation Behind React Fiber: Time Slicing & Suspense Part 2: Why React Had to Build Its Own Execution Engine Part 3: How React Finds What Actually Changed Prerequisites: Read Parts 1–3 first.

A Question Before We Start

Think about how you fetch data in a React component today. You probably do something like this:

function UserProfile({ id }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
      fetchUser(id).then(data => {
        setUser(data);
        setLoading(false);
      });
    }, [id]);
    if (loading) return <Spinner />;
    return <div>{user.name}</div>;
  }

It works. But look at what you had to do: manage two pieces of state, write an effect, handle the loading condition manually, repeat this pattern in every component that fetches data.

Now look at what Suspense lets you write instead:

function UserProfile({ id }) {
  const user = fetchUser(id); // just... read the data
  return <div>{user.name}</div>;
}

<Suspense fallback={<Spinner />}>
  <UserProfile id={1} />
</Suspense>

No loading state. No effect. No condition. The component just reads data as if it’s already there. If it isn’t, React handles the waiting — including showing the spinner — automatically.

How is this possible? How can a component just “pause” mid-render and resume when data arrives?

The answer involves a concept called algebraic effects — and understanding it will make Suspense, ErrorBoundary, and some of React’s most surprising behaviors finally make sense.

Start With Something You Already Know: throw

Algebraic effects sound academic. But Dan Abramov wrote one of the best explanations of them, and he started with something every JavaScript developer already knows: try / catch.

Here’s how throw works:

function getName(user) {
  if (user.name === null) {
    throw new Error('no name');
  }
  return user.name;
}

try {
  getName(user);
} catch (err) {
  console.log('handled:', err.message);
}

Notice what throw actually does. It doesn't decide what happens when the error occurs. It just signals that something happened. The catch block somewhere up the call stack is what decides the behavior.

This separation — signaling something vs handling it — is the core idea.

And notice: it doesn’t matter how deep getName is in the call stack. It could be called 100 functions deep. throw bypasses all of them and finds the nearest catch. The middle layers don't have to do anything. They don't even know about the error.

The Problem With try / catch: No Coming Back

try / catch has one limitation that matters a lot.

When you throw, execution stops at that point. The catch block runs. And that's it — you can never go back to the line that threw and continue from there.

function getName(user) {
  if (user.name === null) {
    throw new Error('no name');
    // ← once you throw, you can NEVER resume here
  }
  return user.name;
}

For errors, this makes sense. But what if you wanted to ask the surrounding context a question and then continue based on the answer?

Like: “I need this user’s name. I don’t have it. Can someone provide it? I’ll wait here.”

That’s what algebraic effects enable. Dan Abramov described it as a “resumable try / catch."

Algebraic Effects: A Resumable try / catch

Algebraic effects don’t exist in JavaScript yet. They’re a research concept — supported only by a handful of languages built specifically to explore the idea. But Dan Abramov explained them using a hypothetical JavaScript dialect, and his explanation is the clearest one I’ve found. Let’s walk through it.

Imagine JavaScript had two new keywords: perform and resume with.

perform works like throw — it signals something to the surrounding context and finds the nearest handler up the call stack. The crucial difference: it doesn't stop execution. The handler can call resume with to jump back to exactly where perform was called and continue from there, passing a value back in.

Here’s Dan’s example. We have a function that needs a user’s name but doesn’t have it:

// Hypothetical JavaScript — this doesn't exist yet
function getName(user) {
  if (user.name === null) {
    // 1. Signal: "I need a name" — but don't stop
    const name = perform 'ask_name';
    // 4. Resume here — name is now 'Arya Stark'
  }
  return user.name;
}

try {
  makeFriends(arya, gendry);
} handle (effect) {
  if (effect === 'ask_name') {
    // 2. Handler catches it - like catch
    // 3. Resume with a value - unlike catch
    resume with 'Arya Stark';
  }
}

The numbered steps show what happens: perform signals (1), the handler catches it (2), the handler provides a value (3), execution jumps back to where perform was and continues with that value (4).

Notice what this doesn’t require. makeFriends — the function between getName and the handler — doesn't know anything about this. It didn't have to be modified. It didn't have to pass anything through. The effect just bypassed it entirely, exactly like throw bypasses intermediate functions on its way to catch.

This is what Dan calls “a function has no color.” With async/await, making one function async infects every function above it — they all have to become async too. With algebraic effects, a deeply nested function can perform an effect without any of the layers above it caring. The handler somewhere at the top decides what to do, and execution resumes as if nothing unusual happened.

What makes this more powerful than try / catch

With regular try / catch, the handler is always synchronous and can never return a value back to the thrower. With algebraic effects, the handler can:

• Respond synchronously — resume with an immediate value
• Respond asynchronously — call resume with inside a setTimeout or after a fetch
• The code that did perform doesn't need to know which one happened

This last point is the key. The same getName function works whether the handler looks up the name from memory, fetches it from a database, or generates it randomly. The function that needs the effect is completely decoupled from how the effect is fulfilled.

That decoupling — signal here, handle somewhere above, resume back here — is the entire concept. And it maps almost exactly onto what React does with Suspense.

Suspense Is React’s Implementation of This Idea

JavaScript doesn’t actually have perform and resume with. They don't exist. But React simulates this pattern using the tools JavaScript does have: throw and Fiber.

Here’s what actually happens when a component suspends:

The component throws a Promise.

When fetchUser(id) is called and the data isn't in the cache yet, instead of returning null or undefined, it throws a Promise — the Promise that will resolve when the data arrives.

// Inside the data fetching library
function fetchUser(id) {
  const cached = cache.get(id);

if (cached === 'pending') {
    throw promise; // ← this is the "perform"
  }
  if (cached === 'resolved') {
    return cache.get(id); // ← data is ready, return normally
  }
  // Start the fetch, mark as pending, throw
  const promise = fetch(`/users/${id}`).then(data => cache.set(id, data));
  cache.set(id, 'pending');
  throw promise;
}

React catches the thrown Promise.

Because React’s render loop runs inside a try / catch, it catches the thrown Promise. This is the "handler" in the algebraic effects model — React itself acts as the effect handler.

React shows the fallback.

React walks up the Fiber tree to find the nearest <Suspense> boundary and shows its fallback — the <Spinner /> — while waiting.

When the Promise resolves, React retries.

When the data arrives, React re-renders the component from the <Suspense> boundary downward. This time, the cache has the data. fetchUser returns normally instead of throwing. The component renders successfully.

As Sam Galson described it:

“A component is able to suspend the fiber it is running in by throwing a promise, which is caught and handled by the framework. When the promise resolves, its value is added to a cache, the fiber is restarted, and the next time the data is requested it is accessed synchronously from cache.”

Why This Only Works Because of Fiber

Here’s the critical question: when a component throws mid-render, wouldn’t all the work React did to reach that point be lost?

With the old synchronous call stack — yes. Throwing would unwind the entire stack, destroying every local variable and stack frame on the way up.

But React uses Fiber, not the native call stack, to track rendering work. Fibers are plain JavaScript objects — they survive the throw. They sit in memory exactly as they were.

When React catches the thrown Promise and shows the fallback, all the Fiber work up to that point is preserved. When the data arrives and React retries, it resumes from the Suspense boundary without re-doing all the ancestor work.

This is what Sam Galson meant when he wrote that the throw-based approach “isn’t problematic for React because it relies on fibers not the native call stack to track program execution.”

Fiber made algebraic-effect-style control flow possible in JavaScript. Without Fiber, throwing a Promise would be catastrophic. With Fiber, it’s just a pause.

ErrorBoundary Is the Same Pattern

Once you understand Suspense through this lens, ErrorBoundary becomes obvious — it’s the same mechanism, just for actual errors instead of Promises.

When a component throws an error during rendering, React walks up the Fiber tree looking for the nearest class component that implements getDerivedStateFromError. When it finds one, it re-renders that component with error state, showing the fallback UI instead of the crashed subtree.

The component that threw didn’t decide what happens — it just threw. The ErrorBoundary somewhere up the tree decided the behavior. Sound familiar?

That’s the same separation as perform and handle. The throwing component signals something happened. The handler decides what to do.

class ErrorBoundary extends React.Component {
  static getDerivedStateFromError(error) {
    return { hasError: true }; // ← this is the "handle"
  }

render() {
    if (this.state.hasError) {
      return <h1>Something went wrong.</h1>;
    }
    return this.props.children;
  }
}

The key difference from Suspense: ErrorBoundary doesn’t resume. Once a component threw an error, that render is abandoned. The boundary re-renders with fallback. Suspense, by contrast, genuinely retries the original render when the data arrives.

The Bigger Picture

Dan Abramov wrote in his algebraic effects article that the React team — specifically Sebastian Markbåge — had been using algebraic effects as a mental model for years:

“My colleague Sebastian kept referring to them as a mental model for some things we do inside of React. At some point, it became a running joke on the React team.”

Hooks follow the same idea too. When you call useState inside a component, that component doesn't know or care where its state is actually stored. It just performs a "request for state" and React — the handler — provides it from the Fiber's hook linked list. The component doesn't reach into React's internals. React provides the value through the call.

This separation — components declaring what they need, React deciding how to provide it — is algebraic effects thinking applied to a UI library. And it’s why React’s API feels declarative even when the underlying behavior is complex.

What’s Coming in Part 5

In Part 5 we look at the React lifecycle from the inside — initial mount, re-render, useEffect, and useLayoutEffect. We'll trace exactly when each fires, why the order is what it is, and what "after the browser paints" actually means.

🎬 Watch These

Sam Galson — Magic in the web of it: coroutines, continuations, fibers | React Advanced London The CS foundation — fibers, coroutines, and how React uses the throw/catch mechanism to simulate algebraic effects. The source for the Fiber + algebraic effects connection in this article.

Matheus Albuquerque — Inside Fiber | React Summit 2022 Start at 12:46 — Matheus shows how Context API was designed using algebraic effects thinking, and how Suspense connects to it.

🙏 Sources & Thanks

• Dan Abramov — Algebraic Effects for the Rest of Us on overreacted.io. The full three-step build in this article — try/catch → limitation → perform/resume with — follows Dan's progression directly. The Arya Stark example, the "resumable try/catch" framing, the "function has no color" insight about async infection, the async handler example, and the quote about Sebastian Markbåge using algebraic effects as a running joke on the React team — all come verbatim or paraphrased from this article. Read it after this one.
• Sam Galson — Magic in the web of it (talk) and Continuations, coroutines, fibers, effects (article). The quote about how “a component is able to suspend the fiber it is running in by throwing a promise” and the throw-handle-resume pattern description come directly from Sam’s article.
• Sebastian Markbåge — for the original “Poor man’s algebraic effects” gist that modeled the technique later used by React Suspense, cited in Sam Galson’s article.
• jser.dev — source verification of how throwException, the Suspense retry mechanism, and ErrorBoundary recovery actually work in the React codebase.

Part 5 is next — the React lifecycle from the inside: when useEffect and useLayoutEffect fire, and why the order is exactly what it is. 🔧

Tags: #react #javascript #webdev #tutorial

How React Works (Part 4)? The Idea That Makes Suspense Possible was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

Not because I had nothing to say. I had everything to say. Every time I solved a hard problem or finally understood something deeply — I wrote it down. That feeling of a light turning on after days of confusion? I wanted to give that to someone else.

But perfectionism had other plans.

Drafts Everywhere

Medium. DEV Community. Google Docs. Chunks of paper stuffed inside books, sitting at the bottom of my laptop bag, falling out when I least expect it.

But I never wanted to publish something incomplete. No article without proper diagrams. No explanation that left gaps. It had to be whole — or it wasn’t going out.

So every draft just sat there — waiting for the perfect diagram, the perfect depth of knowledge, the feeling that I truly understood every part of the topic before I had the right to explain any of it.

Three years of “not yet.”

What I Was Perfectionist About

Not grammar. Not formatting. Something deeper.

I wanted to make it easy to understand — the kind of explanation where someone finishes and thinks why didn’t anyone explain it like this before? I wanted great visualizations that make things clear. I wanted to cover everything so no one gets lost halfway.

Underneath all of that was a quiet fear: the fear of not being good enough. Of not actually helping someone the way they needed.

The Thing Jack Harrington Says

Jack Harrington says it in almost every video:

Easy peasy lemon squeezy.

At some point I actually heard what he was saying — if you understand something well enough, you can make it feel light for someone else. The complexity is real. The explanation doesn’t have to be heavy.

And he uses tools. He doesn’t spend three days hand-crafting a perfect diagram when ChatGPT can make a clear one in five minutes.

So I started doing the same. And suddenly the wall was gone.

The goal was never to be perfect. It was always that moment — when something becomes clear for someone. A perfect article in a draft helps nobody. An honest one out in the world might change how someone thinks forever.

I Cut the Code. I Kept the Story.

I stopped trying to cover everything. Instead I focused on the problem-solution mindset — don’t just show the answer, show the journey. The steps, the wrong turns, how the solution was actually found.

That’s how I learn best. Not from clean final answers — from watching someone walk the path. You can see it in my React series: articles that don’t just explain how React works, but trace why each piece exists. The journey, not just the destination.

What Finally Got Published

Two series. Many articles. Years of drafts — finally out.

⚛️ How React Works Under the Hood — 9 parts. From why Fiber exists to Server Components and hydration. The series I most wanted to find when I was learning and never could.

🔧 Extending bpmn-io Form-JS Beyond Its Limits — 23 parts. The architecture the official docs never wrote. Everything I had to discover through trial and error — so you don’t have to.

The Real Lesson

Wanting clarity, great visuals, and depth — none of that is wrong.

But perfectionism becomes a trap the moment it stops making the work better and starts stopping the work from existing.

So — what’s yours? What have you been sitting on because it’s just not ready yet?

Easy peasy lemon squeezy — not because it’s easy. Because you did the hard work, so the reader doesn’t have to do it alone.

Sam Abaasi — Frontend Engineer Medium · DEV Community · LinkedIn