Understand Astro islands and partial hydration

Introduction

Islands are the mental model behind Astro’s promise to ship less JavaScript. This post explains server rendering, client directives, and how to decide when an interactive component is worth its hydration cost.

Field notes

A few patterns we kept seeing while puttering around Astro problems:

• The simple version survived every refactor; the clever version didn’t.
• Documentation written during the work aged far better than documentation written after.
• The second time a problem shows up, it is already a pattern — name it.

A checklist you can steal

• The failure is reproducible with one command.
• The fix has a test that fails without it.
• Someone other than the author has run it on their machine.

Closing

Write the short version future-you will actually read. That is the whole trick.