Skip to content

Astro

core

Assumes you have read: Rendering strategies, TypeScript's Type System

Astro renders components to HTML and sends client JavaScript only for components explicitly made interactive. An island is a boundary: static content stays HTML while a widget gets its own hydration policy. The rendering-strategies page owns the timeline vocabulary.

<SearchBox client:visible />

The server emits markup; client:visible delays the island’s module and hydration until it enters the viewport. Checked against Astro 7.2.2 documentation, 2026-08-17: islands and directives.

If a page has islands i1...ik, shipped client code is approximately the sum of their reachable chunks plus shared runtime, rather than a whole-site application bundle. Initial interactive work is the sum of islands eligible at load; client:visible moves an island’s download and hydration later, trading immediate readiness for lower startup work. Static HTML shifts recurring render work to build time, while server rendering pays it per request; measure output bytes, island script bytes, and interaction latency separately.

Do not use Astro when nearly every element is continuously interactive and cross-component client state dominates; a client application can make that boundary simpler. Do not add an island for content that never responds to input. Avoid client:load everywhere: it gives up the startup budget islands are meant to protect.

Astro is a strong fit for documentation, editorial, marketing, and commerce pages with a mostly stable content surface and a few interactive search, purchase, or visualization widgets.

A widget is visible but inert. The symptom is HTML with no click behavior; its directive delayed hydration or its client module failed. Use the appropriate directive and monitor island errors. A page becomes a client app by accident. Many client:load islands duplicate runtime and hydration work; inspect the generated scripts and move non-critical widgets to visibility or idle. Two islands disagree about shared state. Separate islands do not share component memory automatically; move coordination to a deliberate client boundary or URL/server state.

  1. Ten charts use client:load. Solution: measure each chart’s visibility and move below-fold charts to client:visible; compare startup JS and first interaction.
  2. A nav must work before any script. Solution: keep navigation as links/server HTML and enhance only the optional behavior; test with JavaScript disabled.

Astro ships HTML by default and hydrates explicit islands, so client bytes and startup work scale with chosen interactive boundaries. The caveat is coordination: islands reduce shared runtime assumptions, and over-hydrating them recreates the application cost.