Ramonda

@deferHydration

Declares the method that says when this component may hydrate. Until the promise it returns settles, the subtree is left exactly as the server wrote it.

The situation it is for

A panel whose contents live in a chunk that is loaded on demand. The server has the component and renders it fully. The browser, on its first pass, does not — the chunk has not arrived — so it would render a spinner where finished content already is, and hydration would replace the good markup with it.

class Panel extends Component<{ id: string }> {
  private ready = false;

  @deferHydration
  untilLoaded() {
    return this.load();
  }

  async load(): Promise<void> {
    await import("./heavy-chart");
    this.ready = true;
  }

  render() {
    return <section>{this.ready ? <p>Chart</p> : <p>Loading…</p>}</section>;
  }
}

With the decorator, the subtree is left exactly as the server wrote it until the promise settles. The reader sees the finished chart the whole time; nothing flashes.

Without it they watch finished content turn into a spinner and back — on a page that was already correct, which is what makes this fault so unpleasant to meet.

The problem it exists for

Hydration adopts the server's DOM by rendering the same tree in the browser and matching it up. A component whose output depends on something not ready yet renders a fallback instead — and the fallback does not match, so the real markup is replaced by it.

The reader watches finished content flash into a spinner. That is the whole fault, and it only happens on a page that was already correct.

AsyncLoad uses this for you. You need it yourself only if you build something with the same shape: markup the server could produce and the browser cannot, until something loads.

What it refuses

Anything but a method. It has to call something to get a promise.

What it costs

The subtree stays inert until the promise settles: server markup on screen, no listeners attached, nothing interactive inside it. That is the trade — correct pixels instead of early clicks — and a promise that never settles is a subtree that never wakes up.

Next