hnq.me
all concepts
client Updated 2026-07-09 Step 6 of 6

Hydrate

A beginner-friendly guide to understanding hydration and small UI runtimes.

On this page 2026-07-09
The Simple Idea Why Hydration Exists Static HTML vs Interactive HTML Classic Hydration The Hydration Cost Attribute Hydration Hydration And Server Truth Hydration And Runtime KitJS And Kitwork Notes My Learning Notes Common Misunderstandings Related Concepts

A beginner-friendly guide to hydration: making already-rendered HTML interactive with a client runtime.

Hydration is about connecting behavior to HTML that already exists.

The server can send meaningful HTML first.

Then the client runtime attaches interaction.

HTML arrives -> runtime boots -> behavior attaches

Table of Contents

The Simple Idea

Hydration turns visible HTML into interactive HTML.

The HTML may already be on the screen.

Hydration adds behavior.

server renders HTML
browser displays HTML
client runtime connects behavior
page becomes interactive

Why Hydration Exists

Server-rendered HTML is useful because it can appear quickly and be readable before JavaScript finishes loading.

But HTML alone is not enough for many interfaces.

Users need:

  • buttons,
  • forms,
  • tabs,
  • counters,
  • validation,
  • live updates,
  • navigation,
  • small state changes.

Hydration connects the visible page to the client runtime.

Static HTML vs Interactive HTML

Static HTML can show information.

Interactive HTML can respond.

Example:

<button>Save</button>

Static version:

it looks like a button

Hydrated version:

it can submit, validate, show state, or trigger behavior

Hydration is the bridge.

Classic Hydration

In many frameworks, hydration means the client downloads JavaScript, reconstructs or reconnects a component tree, and attaches event handlers to server-rendered HTML.

The mental model:

server renders HTML
client downloads app
client matches app to HTML
client takes over interactivity

This can work very well.

It can also be heavy.

The Hydration Cost

Hydration can cost:

  • JavaScript payload,
  • parsing time,
  • framework runtime,
  • duplicate server/client logic,
  • component tree reconstruction,
  • event handler setup,
  • debugging complexity.

Hydration is not bad.

It is simply not free.

Good architecture asks:

how much hydration does this page actually need?

Attribute Hydration

A smaller model is possible.

Instead of shipping a full client app, HTML can carry small behavior instructions:

<button data-click="count = count + 1">+</button>
<b data-text="count"></b>

The runtime reads attributes.

The attributes describe behavior.

The page stays HTML-first.

This is still hydration.

The surface is smaller.

Hydration And Server Truth

Hydration does not have to move truth to the client.

A page can be:

server-rendered for truth
client-hydrated for interaction

The server can own:

  • data,
  • permissions,
  • tenant boundaries,
  • SEO-visible content,
  • canonical results.

The client runtime can own:

  • local interaction,
  • form hints,
  • toggles,
  • small state,
  • live updates.

Hydration And Runtime

Hydration needs a runtime because something must:

  • scan the page,
  • understand directives,
  • evaluate expressions,
  • track state,
  • attach behavior,
  • update the DOM,
  • handle navigation or live updates.

The runtime can be large or small.

The design question is:

what is the smallest runtime that can make this HTML interactive?

KitJS And Kitwork Notes

KitJS made hydration feel practical. HTML could arrive already useful, then a small runtime could attach behavior only where the page asked for it.

That changed how I think about frontend work. Hydration does not have to mean turning the whole page into an app. It can mean attaching a few precise behaviors to server-rendered HTML.

Kitwork uses that lesson as part of its architecture: render on the server, keep the page readable, then hydrate the client side with runtime JS when interaction is needed.

My Learning Notes

I used to think hydration meant "a framework takes over the page."

Later, while working with KitJS-style runtime, I started seeing hydration more simply:

HTML already exists
small attributes describe behavior
a tiny runtime connects them

That changed the question for me.

Instead of asking:

which client framework should own this page?

I started asking:

what behavior does this HTML actually need?

The lesson:

hydration does not have to mean a large client app
hydration can mean giving HTML just enough behavior

Common Misunderstandings

"Hydration means React."

No. React uses hydration, but hydration is a broader idea.

"Hydration is always bad."

No. It solves a real problem. The question is how much hydration a page needs.

"Server-rendered HTML cannot be interactive."

It can. It needs a client runtime to attach behavior.

"Small hydration is not real hydration."

If HTML becomes interactive after a runtime connects behavior, it is a form of hydration.

Previous: reactive

Next: jit

Related: directive, servertruth, blueprint

Search