---
name: web-addon-astro
description: Astro server-first conventions — zero client JS by default, island hydration directives, content collections, and static vs server rendering. Use when working in an Astro project, adding islands, or deciding hydration strategy for a content-heavy site.
---

## Addon — Astro

Astro is server-first and ships **zero client JavaScript by default**. Keep it
that way — only hydrate what genuinely needs interactivity.

**Components & hydration:**
- `.astro` components render to HTML at build/request time and ship no JS.
- Use a framework component (React/Vue/Svelte/Solid) only for an interactive
  island, with a hydration directive: `client:load` (immediately),
  `client:idle` (when the main thread is idle), `client:visible` (when scrolled
  into view — prefer this below the fold), `client:only="react"` (skip SSR).
- No directive = static HTML, no JS. That is the goal for most of the page.
- `server:defer` makes a component a server island — defer slow or personalized
  server work so the rest of the page streams immediately.

**Content:**
- Manage structured content (blog, docs, products) with content collections in
  `src/content.config.ts` — a Zod schema for type-safety plus a `loader` for the
  source (local files or a remote API/CMS). Query with `getCollection`.

**Rendering mode:**
- `output: 'static'` (default) prerenders every route. Use `output: 'server'`
  with an adapter only when request-time rendering or endpoints are needed; a
  single route can opt back in with `export const prerender = true`.

**Do not:**
- Do not add a `client:*` directive to a component with no interactivity.
- Do not reach for Astro when every screen is a stateful app — that is a SPA.
- Keep secrets server-side; only `PUBLIC_`-prefixed env vars reach the client.