Astro — Claude Code rules

You are working in an Astro project (islands architecture, content-driven sites). The core principle: render to HTML & CSS and ship zero client-side JavaScript by default. Add JS only where interactivity is genuinely needed.

Components (.astro)

• A .astro file has a component script in a code fence (---) and a template below it.
• The component script runs at build time / on the server only. It is stripped from the page sent to the browser — put imports, data fetching, and API calls here.
• The template is HTML with { } expressions referencing script variables.
• Props come in via Astro.props. Define an interface Props for type safety, e.g. const { title } = Astro.props;. Support defaults in the destructure when useful.
• Use <slot /> for children; named slots via <slot name="x" /> + slot="x" on the child. Provide fallback content inside the slot when no children are passed.
• Compose pages from small components. Astro components render with zero client JS by default.

Islands & hydration (client: directives)

• An island is an interactive UI component on an otherwise static page. Islands run in isolation and hydrate independently, in parallel — they don't block each other.
• Only components marked with a client:* directive ship JavaScript. Pick the lightest one:
  • client:load — hydrate immediately on page load (high-priority, above-the-fold UI).
  • client:idle — hydrate once the browser is idle (lower-priority UI).
  • client:visible — hydrate only when the component scrolls into view (default for most things).
  • client:media={QUERY} — hydrate when a CSS media query matches.
  • client:only="react" — skip server render; render on the client only (name the framework).
• No directive = static HTML, no JS. Don't add client:* to anything that isn't interactive.
• For dynamic server-rendered content, use a server island via the server:defer directive instead of shipping client JS.
• Plain .astro components cannot take client:* — only framework components hydrate.

UI framework components (React / Vue / Svelte / Preact / Solid)

• Without a directive, framework components also render to static HTML — no JS shipped.
• Only Astro components can mix multiple frameworks on one page. Framework components cannot import .astro files.
• Props passed to a hydrated island must be serialisable (objects, numbers, strings, Arrays, Map, Set, Date, RegExp, URL, BigInt, typed arrays). Functions cannot be passed.
• Children: React/Preact/Solid use a children prop; Svelte/Vue use <slot />.

Content (content collections)

• Manage structured content (blog posts, docs, etc.) with content collections, stored outside src/pages/.
• Define collections in src/content.config.ts with defineCollection(), exported as a single collections object.
• Use a loader: glob() for a directory of Markdown/MDX/JSON/YAML/TOML, file() for one file with many entries. Set the base path explicitly.
• Give each collection a Zod schema for validated, type-safe frontmatter, e.g. z.object({ title: z.string(), pubDate: z.coerce.date() }). Schemas are optional but recommended.
• Query with getCollection('blog') and getEntry('dogs', 'poodle') from astro:content.
• Render entries with the standalone render(): const { Content } = await render(entry);.
• Link entries across collections with reference().

Don't

• Don't add client:* to non-interactive components, or reach for a framework when plain Astro + a small <script> will do.
• Don't pass functions (or non-serialisable values) as props to a hydrated island.
• Don't import a .astro component from inside a framework component.
• Don't put content collection files under src/pages/, and don't skip the Zod schema.
• Don't expect client:only components to render on the server — they won't.