astro
Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is `nextjs`).
ericrisco · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ericrisco/rsc-harness --skill astroAbout this skill
name: astro
description: "Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is nextjs)."
tags: [astro, ssg, islands, content-collections, partial-hydration, marketing-site, frameworks]
recommends: [landing-copy, seo-geo, vercel, cloudflare, netlify]
origin: risco
Astro 6 — static-first sites, islands, content collections
The prime directive
Ship zero client JavaScript by default. Hydrate the smallest possible surface, as late as you can
get away with. An .astro component renders to HTML at build time and ships no runtime; every
island is a bundle the visitor downloads, parses, and executes. Content and marketing sites win on
TTFB/LCP and Lighthouse, not on React-everywhere. If you find yourself adding client:load to make
a page "work," stop — the page already works; you are adding interactivity, and interactivity is the
expensive exception, not the default.
First: detect the project version
Astro 6.0 is stable (released 2026-03-10); the Astro 5 line is
still production-ready. Do not mix advice across majors — read package.json → the astro version
before advising. What v6 changes, per the
upgrade-to-v6 guide:
- Node
22.12.0or higher is required (18 and 20 are dropped) — check the actual runtime. - Content config lives at
src/content.config.ts. The legacysrc/content/config.tspath is removed, not merely discouraged, and the old auto-detection (legacy.collections) is gone. Thelegacy.collectionsBackwardsCompatescape hatch is a migration crutch, not a supported layout. - Vite 7 and Zod 4 for content schemas —
zis imported fromastro/zod, notastro:content(see Content collections below). - Live Content Collections, the Fonts API and the CSP API are stable.
- The Rust compiler succeeding the Go one is experimental — do not rely on or configure it in production advice.
Decision table — what kind of thing is this?
Pick the cheapest row that satisfies the requirement. Read top-down; stop at the first match.
| Need | Use | Why |
|---|---|---|
| Pure content, no interactivity | .astro component, static | Renders to HTML at build, ships 0 KB JS |
| One small interactive widget | UI-framework component + client:* | Hydrate just that island; the rest stays static |
| Per-request personalization on a mostly-static page | server island (server:defer) | Static CDN page + one deferred fragment, no full SSR |
| Whole route needs request data on every load | export const prerender = false + adapter | Opt that one route into on-demand rendering |
| Many static routes generated from data | getStaticPaths() | Build-time fan-out, still fully static |
Rendering model
Default: every page is prerendered to static HTML at build time. You opt into dynamism per route — never the other way around.
---
// src/pages/dashboard.astro — opt this ONE route into on-demand (SSR) rendering.
// Requires a configured adapter (Vercel/Netlify/Cloudflare/Node). Everything else stays static.
export const prerender = false;
const user = await getUser(Astro.request); // runs per request
---
<h1>Hello {user.name}</h1>
---
// src/pages/blog/[slug].astro — many STATIC routes generated from data at build time.
import { getCollection } from "astro:content";
export async function getStaticPaths() {
const posts = await getCollection("blog");
return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
}
const { post } = Astro.props;
---
<h1>{post.data.title}</h1>
In Astro 6 the dev server runs the production runtime (Vite 7 Environment API), so dev no longer
diverges from prod on Cloudflare/Bun/Deno — fewer "works in dev, breaks on deploy" surprises. Adapter
choice per platform → references/deploy-and-integrations.md.
Islands & client directives
A client:* directive turns a framework component into a hydrated island. Choose the latest
directive that still feels instant to the user — never default to client:load.
| Directive | Hydrates when | Use for |
|---|---|---|
client:load | Immediately on page load | Above-the-fold, must-be-interactive-now controls |
client:idle | On requestIdleCallback | Important but not first-paint-critical widgets |
client:visible | When it scrolls into view (IO) | Below-the-fold carousels, comment boxes, maps |
client:media={query} | When a media query matches | Mobile-only menu, desktop-only panel |
client:only="react" | Client-only, no SSR HTML | Components that crash during SSR (browser-only deps) |
---
import Carousel from "../components/Carousel.tsx";
---
<!-- Bad: a below-the-fold carousel paying for JS at first paint -->
<Carousel client:load />
<!-- Good: defer its bundle until the user actually scrolls to it -->
<Carousel client:visible />
client:only gotcha: