Astro 6 Islands

A skill for building production content sites with Astro 6 — server islands for dynamic regions inside static pages, the Content Layer API for type-safe collections, partial hydration directives, and Cloudflare deployment. It's aimed at developers shipping blogs, docs, and marketing sites who want mostly-static HTML with selectively dynamic and interactive bits, without turning the whole page into an SPA.

When to use it

• A page is statically generated, but one region (cart count, personalized greeting, live stock) must be per-request. Reach for a server island instead of making the whole route SSR.
• You're pulling content from Markdown/MDX on disk, or from a CMS/API, and want validated, typed entries.
• You have a React/Vue/Svelte widget that should ship zero JS until it's actually needed.
• You're deploying to Cloudflare Workers/Pages and want the adapter wired correctly.

How it works

Server islands use the server:defer directive on a component. Astro renders the static shell immediately and streams the island's HTML in afterward from the server. Provide a placeholder with the named fallback slot:

<Avatar server:defer>
  <div slot="fallback">Loading…</div>
</Avatar>

Content Layer API defines collections in src/content.config.ts with defineCollection, a loader, and a Zod schema. Built-in glob() and file() loaders cover local content; you can write a custom loader for remote sources. Query with getCollection() / getEntry(), and render() to get the <Content /> component (MDX supported via @astrojs/mdx).

// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({ title: z.string(), date: z.coerce.date(), draft: z.boolean().default(false) }),
});
export const collections = { blog };

Client directives control hydration of framework components: client:load, client:idle, client:visible, and client:media="(max-width: 50em)".

curl -fsSL --create-dirs -o ~/.claude/skills/astro-6-server-islands/SKILL.md https://claudeskil.com/skills/astro-6-server-islands/SKILL.md
npm create astro@latest
npx astro add cloudflare

Tips & gotchas

• Server islands require an adapter and an SSR-capable host; on a fully static build with no adapter they won't defer.
• Island props are encrypted and sent to the server, but don't pass secrets through them — treat the boundary like any request input.
• The config file is src/content.config.ts in Astro 6 (the old src/content/config.ts location is legacy). Run astro sync to regenerate astro:content types after schema edits.
• client:only="react" skips SSR entirely — use it only for components that can't render on the server.

FAQ

Server island vs. client:* directive? Server islands defer server-rendered HTML (no client JS, good for personalization). Client directives hydrate interactive components in the browser.

Can I cache a server island? Yes — set response/Cache-Control headers in the island; each island is its own request and can be cached independently of the shell.

Do I need a database for the Content Layer? No. glob/file loaders read local files; a custom loader handles remote APIs.