Astro Agent Skill

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.0 or higher is required (18 and 20 are dropped) — check the actual runtime.
• Content config lives at src/content.config.ts. The legacy src/content/config.ts path is

removed, not merely discouraged, and the old auto-detection (legacy.collections) is gone.

The legacy.collectionsBackwardsCompat escape hatch is a migration crutch, not a supported layout.

• Vite 7 and Zod 4 for content schemas — z is imported from astro/zod, not

astro: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: it skips SSR entirely, so the component produces no server HTML (expect a

flash/layout shift) and you must name the framework (client:only="react") — Astro can't infer

it without the server render. Reach for it only when SSR genuinely breaks; otherwise prefer

client:visible.

Content collections (Content Layer)

Type-safe content lives in a single config file. The path is load-bearing:

// src/content.config.ts  ← v6 path. NOT src/content/config.ts (legacy path removed in v6)
import { defineCollection } from "astro:content";
import { z } from "astro/zod"; // v6: z moved OUT of astro:content into astro/zod (Zod 4)
import { glob } from "astro/loaders";

const blog = defineCollection({
  // glob() sources files from anywhere; `id` comes from the filename minus extension
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    pubDate: z.coerce.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { blog };

Query and render in a page. render() is now a standalone call (not entry.render()):

---
// src/pages/blog/[slug].astro
import { getCollection, getEntry, render } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog", ({ data }) => !data.draft);
  return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
}
const { post } = Astro.props;
const { Content } = await render(post);
---
<article><h1>{post.data.title}</h1><Content /></article>

Built-in loaders are glob() (many files) and file() (one JSON/YAML array). Custom and CMS

loaders, Zod 4 schema patterns, collection references, Live Content Collections (real-time data with

no rebuild, stable in v6), querying and MDX details → references/content-layer.md.

Server islands

When most of a page is static and CDN-cacheable but one fragment is per-visitor, use a server

island instead of turning the whole route into SSR. The page ships static; the island is fetched

and rendered after first paint.

---
// src/components/UserGreeting.astro — rendered on demand, deferred after the static shell
const user = await getUserFromCookie(Astro.request);
---
<span>Welcome back, {user.name}</span>

---
import UserGreeting from "../components/UserGreeting.astro";
---
<header>
  <!-- static page, one deferred personalized fragment with a placeholder while it loads -->
  <UserGreeting server:defer>
    <span slot="fallback">Welcome</span>
  </UserGreeting>
</header>

This beats full SSR when: the page is otherwise cacheable on a CDN, and only a small slice depends on

the request. You keep static LCP and personalize without making every request hit the origin.

Integrations & setup

Use astro add so it patches astro.config.mjs and installs peers in one step:

npx astro add react mdx sitemap

• Tailwind 4 wires through the official Vite plugin (@tailwindcss/vite), not the legacy

@astrojs/tailwind integration (that path was for Tailwind 3).

• Fonts API (stable in v6) self-hosts and optimizes fonts from astro.config.mjs — no manual

@font-face.

• CSP API (stable in v6) emits a Content-Security-Policy with hashes for your inline

scripts/styles.

Adapter recipes per platform, hybrid rendering, env handling, SSR endpoints (src/pages/api/*.ts)

and the Fonts/CSP config → references/deploy-and-integrations.md.

Performance rules

• Images: always <Image>/<Picture> from astro:assets — automatic width/height, format, and

lazy-loading kill CLS and over-sized payloads. Never a raw <img> for local assets.

• Never global-hydrate: there is no "make the page interactive" switch; hydrate per island.
• View transitions: add <ClientRouter /> from astro:transitions to the <head> for SPA-like

navigation without an SPA. Prefetch links with the prefetch config/attribute.

Astro 5 → 6 migration checklist

Run the codemod first, then verify each item:

npx @astrojs/upgrade

• [ ] Node runtime is 22.12.0+ (CI image, local, deploy target).
• [ ] Dependencies on Vite 7 (Vite v7.0; custom Vite plugins/config may need updates).
• [ ] Schema z import moved: import { z } from "astro/zod" — z and astro:schema are gone

from astro:content. Then review for Zod 4 breaking changes.

• [ ] Content config renamed to src/content.config.ts (delete src/content/config.ts; the

legacy path is removed, not just deprecated).

• [ ] Full guide (dated 2026): docs.astro.build/en/guides/upgrade-to/v6.

Anti-patterns

| Anti-pattern | Reality |

| -------------------------------------------------------- | --------------------------------------------------------------------------- |

| "Add client:load so the page works" | An .astro page already works statically; you're shipping JS for nothing |

| "client:load everywhere, simplest" | Pick client:visible/idle/media; first-paint JS is the LCP killer |

| "Make the whole route SSR to personalize the header" | Use a server island (server:defer); keep the page static & CDN-cached |

| "src/content/config.ts worked before, keep it" | v6 removed that path (LegacyContentConfigError) — must be src/content.config.ts |

| "fetch() the CMS inside the .astro frontmatter" | Write a content-collection loader so content is typed, cached, and queryable |

| "Pull in React just to render this static markup" | Static markup is an .astro component — 0 KB, no framework runtime |

| "Skip the Zod schema, content is just frontmatter" | Untyped content = silent build-time drift; the schema is the contract |

| "client:only without the framework name" | It can't infer the framework with no SSR — must be client:only="react" |

| "Use the old @astrojs/tailwind for Tailwind 4" | Tailwind 4 wires through @tailwindcss/vite; the old integration is v3-era |

Verify

bash scripts/verify.sh from the Astro project root — grep-based, needs no install. It FAILS if

a v6 project still has src/content/config.ts instead of src/content.config.ts, WARNS on

over-hydration smells (many client:load, or client:only with no framework string), CHECKS

that content schemas import from astro:content, and — only if the astro binary resolves —

optionally runs npx astro check. On an empty or clean tree it prints OK and exits 0; warnings are

advisory and never fail the run.

See Also

• ../nextjs/SKILL.md — when the project is really an app-router React app with server actions and

heavy client interactivity, not a content/marketing site.

• ../landing-copy/SKILL.md and ../seo-geo/SKILL.md — this skill builds the site; those write the

copy and decide the SEO/structured-data strategy that fills it.

• ../vercel/SKILL.md, ../netlify/SKILL.md, ../cloudflare/SKILL.md — platform mechanics (DNS,

env, build settings) once the code and adapter are ready.