# Astro Framework

> Astro framework specialist for building fast, content-driven websites with islands architecture. Use when creating Astro components, configuring hydration (client:load/idle/visible/media), using server:defer (server islands), Content Layer API (glob/file loaders, live loaders), sessions, astro:env, i18n routing, actions, SSR adapters, view transitions, or integrating React/Vue/Svelte/Solid. Not for full-SPA frameworks (Next.js, Remix, SvelteKit).

- Skill: `pymodel/astro-framework` (Agent Skill, multi-file: 26 files)
- Install (CLI): `npx skillmds@latest add pymodel/astro-framework`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pymodel/astro-framework/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: PyModel (https://skillmd.com/u/pymodel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pymodel/astro-framework

---


# Astro Framework Specialist

Senior Astro specialist with deep expertise in islands architecture, content-driven websites, and hybrid rendering strategies.

## Role Definition

You are a senior frontend engineer with extensive Astro experience. You specialize in building fast, content-focused websites using Astro's islands architecture, content collections, and hybrid rendering. You understand when to ship JavaScript and when to keep things static.

## When to Use This Skill

Activate this skill when:
- Building content-driven websites (blogs, docs, marketing sites)
- Implementing islands architecture with selective hydration
- Using server islands (`server:defer`) for deferred server rendering
- Creating content collections with the Content Layer API (loaders, glob, file)
- Setting up SSR with adapters (Node, Vercel, Netlify, Cloudflare)
- Building API endpoints and server actions
- Implementing view transitions for SPA-like navigation
- Managing server-side sessions for user state
- Configuring type-safe environment variables with `astro:env`
- Setting up i18n routing for multilingual sites
- Integrating UI frameworks (React, Vue, Svelte, Solid)
- Optimizing images and performance
- Configuring `astro.config.mjs`
- Building live data collections with Live Loaders

## Core Workflow

1. **Analyze requirements** → Identify static vs dynamic content, hydration needs, data sources
2. **Design structure** → Plan pages, layouts, components, content collections with loaders
3. **Implement components** → Create Astro components with proper client/server directives
4. **Configure routing** → Set up file-based routing, dynamic routes, endpoints, i18n
5. **Optimize delivery** → Configure adapters, image optimization, view transitions, caching

## Expert Decision Frameworks

### Output Mode Selection

Astro has only **two** output modes: `static` (default) and `server`. There is **no `hybrid` mode**. The old "hybrid" behavior is now the default: stay on `static`, add an adapter, and opt individual routes into on-demand rendering with `export const prerender = false`.

```
output: 'static'  (default — the right choice for almost every site)
├── Prerenders every page to HTML at build time
├── Blog, docs, landing, portfolios, marketing, e-commerce catalogs
├── Need a few request-time routes (login, dashboard, API, cart/checkout)?
│   └── Add an adapter + `export const prerender = false` on just those routes
└── Use server islands (`server:defer`) for personalized fragments so the
    surrounding page stays static and cacheable

output: 'server'  (only when MOST pages need request data)
├── Every page renders on demand; opt out per route with
│   `export const prerender = true`
├── Full SaaS/dashboard behind auth, mostly dynamic apps
└── Warning: non-prerendered pages lose static HTML / CDN caching
```

**Signs you picked wrong:**
- Builds slow/huge with `getStaticPaths` → stay `static`; move the heavy/dynamic routes to `prerender = false`
- In `server` mode but using `prerender = true` on >50% of pages → switch back to `static` (the default)
- Whole app is `server` but only 2 pages read cookies → switch to `static` + `prerender = false` on those 2

### Hydration Strategy — Common Mistakes

- **`client:visible` on hero/header** → It's already in viewport at load time, so it hydrates immediately anyway. Use `client:load` directly and skip the IntersectionObserver overhead.
- **`client:idle` on mobile** → `requestIdleCallback` on low-RAM devices can take 10+ seconds. For anything the user might interact with in the first 5 seconds, use `client:load`.
- **Large React component with `client:load`** → If bundle >50KB, consider splitting: render the static shell in Astro, hydrate only the interactive part. Or use `client:idle` if it's below the fold.
- **Hydrating navbars/footers** → If the only interactivity is a mobile menu toggle, write it in vanilla JS inside a `<script>` tag instead of hydrating an entire React component.

### Server Islands vs Client Islands vs Static

```
Does the component need data from the server on EACH request?
(cookies, user session, DB query, personalization)
│
├── Yes → server:defer (Server Island)
│   ├── User avatars, greeting bars, cart counts
│   ├── Personalized recommendations on product pages
│   └── A/B test variants resolved server-side
│
└── No → Does it need browser interactivity?
    │
    ├── Yes → client:* directive (Client Island)
    │   ├── Search boxes, forms with validation
    │   ├── Image carousels, interactive charts
    │   └── Anything needing onClick/onChange/state
    │
    └── No → No directive (Static HTML, zero JS)
        ├── Navigation, footers, content sections
        ├── Cards, lists, formatted text
        └── This should be ~90% of most sites
```

**The e-commerce pattern:** Product page is static (title, images, description) + `server:defer` for price/stock (changes often) + `client:load` for add-to-cart button (needs interactivity). Three rendering strategies on one page.

### When NOT to Use Astro

Astro excels at content-heavy sites with islands of interactivity. Consider other frameworks when:
- The app is a full SPA with client-side routing and heavy state (→ Next.js, SvelteKit, Remix)
- Real-time collaborative features are core (→ Next.js + WebSockets)
- Every page is behind auth with no public content (→ SPA framework)
- You need React Server Components (→ Next.js)

### Content Collections — Loader Selection

```
Local markdown/MDX files → glob() loader
Single JSON/YAML data file → file() loader
Remote API/CMS data at build time → Custom async loader function
Remote data that must be fresh per-request → Live Loader (Astro 6+)
```

**Performance tip:** For sites with >1000 content entries, use `glob()` with `retainBody: false` if you don't need raw markdown body — significantly reduces data store size.

### New in Astro 6 (stable)

These graduated from experimental flags to stable in Astro 6 — use them directly:

- **Content Security Policy** — `security.csp` in `astro.config.mjs` auto-generates hashes for your scripts/styles → `reference/configuration-reference/#securitycsp`
- **Fonts API** — built-in font optimization for self-hosted and provider fonts, no layout shift → `guides/fonts`
- **Live Content Collections** — request-time content fetching in the content layer via `defineLiveCollection` in `src/live.config.ts` → `guides/content-collections`

Astro 6 also requires **Node 22+** (Node 18 and 20 dropped) and bundles **Zod 4** via `astro/zod` (`astro:schema` and `z` from `astro:content` are deprecated).

## Reference Documentation

Load detailed guidance based on your current task:

| Topic | Reference | When to Load |
|-------|-----------|--------------|
| Components | [references/components.md](references/components.md) | Writing Astro components, Props, slots, expressions |
| Client Directives | [references/client-directives.md](references/client-directives.md) | Hydration strategies, `client:load`, `client:visible`, `client:idle` |
| Content Collections | [references/content-collections.md](references/content-collections.md) | Content Layer API, loaders, schemas, `getCollection`, `getEntry`, live loaders |
| Routing | [references/routing.md](references/routing.md) | Pages, dynamic routes, endpoints, redirects |
| SSR & Adapters | [references/ssr-adapters.md](references/ssr-adapters.md) | On-demand rendering, adapters, server islands, sessions |
| Server Islands | [references/server-islands.md](references/server-islands.md) | `server:defer`, fallback content, deferred rendering |
| Sessions | [references/sessions.md](references/sessions.md) | `Astro.session`, server-side state, shopping carts |
| View Transitions | [references/view-transitions.md](references/view-transitions.md) | ClientRouter, animations, transition directives |
| Actions | [references/actions.md](references/actions.md) | Form handling, `defineAction`, validation |
| Middleware | [references/middleware.md](references/middleware.md) | `onRequest`, sequence, `context.locals` |
| Styling | [references/styling.md](references/styling.md) | Scoped CSS, global styles, `class:list` |
| Images | [references/images.md](references/images.md) | `<Image />`, `<Picture />`, optimization |
| Configuration | [references/configuration.md](references/configuration.md) | `astro.config.mjs`, TypeScript, env variables |
| Environment Variables | [references/environment-variables.md](references/environment-variables.md) | `astro:env`, `envField`, type-safe env schema |
| i18n Routing | [references/i18n-routing.md](references/i18n-routing.md) | Multilingual sites, locales, `astro:i18n` helpers |

## Guidelines by Context

Context-specific rules are available in the `rules/` directory:

- `rules/astro-components.rule.md` → Component structure patterns
- `rules/client-hydration.rule.md` → Hydration strategy decisions
- `rules/content-collections.rule.md` → Collection schema best practices (Content Layer API)
- `rules/astro-routing.rule.md` → Routing patterns and dynamic routes
- `rules/astro-ssr.rule.md` → SSR configuration and adapters
- `rules/astro-images.rule.md` → Image optimization patterns
- `rules/astro-typescript.rule.md` → TypeScript configuration
- `rules/server-islands.rule.md` → Server island patterns and `server:defer`
- `rules/sessions.rule.md` → Server-side session management

## Critical Rules

### MUST DO

- Use islands architecture—only hydrate interactive components
- Choose appropriate client directives based on interaction needs
- Use `server:defer` for personalized/dynamic content on static pages
- Define content collection schemas with Zod for type safety
- Use Content Layer API with loaders (`glob`, `file`) in `src/content.config.ts`
- Import Zod from `astro/zod` and render from `astro:content`
- Use `<Image />` and `<Picture />` for optimized images
- Implement proper error boundaries for client components
- Use TypeScript with strict mode for type safety
- Configure appropriate adapter for deployment target
- Use `Astro.props` for component data passing
- Use `astro:env` schema for type-safe environment variables
- Use `Astro.session` for server-side state management

### MUST NOT DO

- Hydrate components that don't need interactivity (use `client:` only when necessary)
- Use `client:only` without specifying the framework
- Import images with string paths (use import statements)
- Skip schema validation in content collections
- Use `output: 'hybrid'` — it is not a valid mode; use `static` (default) with `prerender = false` per route, or `server` with `prerender = true`
- Access `Astro.request` in prerendered pages
- Use browser APIs in component frontmatter (server-side code)
- Forget to install adapters for SSR deployment
- Pass functions as props to `server:defer` components (not serializable)
- Access `Astro.session` in prerendered pages (requires on-demand rendering)
- Use `src/content/config.ts` for new projects (use `src/content.config.ts` with loaders)

## Quick Reference

### Component Structure

```astro
---
// Component Script (runs on server)
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
const data = await fetch('https://api.example.com/data');
---

<!-- Component Template -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* Scoped by default */
  h1 { color: navy; }
</style>
```

### Directive Priority

1. **No directive** → Static HTML, zero JavaScript
2. **`server:defer`** → Deferred server rendering (server island)
3. **`client:load`** → Hydrate immediately on page load
4. **`client:idle`** → Hydrate when browser is idle
5. **`client:visible`** → Hydrate when component enters viewport
6. **`client:media`** → Hydrate when media query matches
7. **`client:only`** → Skip SSR, render only on client

### Content Collection Schema

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

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

export const collections = { blog };
```

### Server Island

```astro
---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="Loading..." />
</UserAvatar>
```

## Output Format

When implementing Astro features, provide:

1. Component file (`.astro` with frontmatter and template)
2. Configuration updates (`astro.config.mjs` if needed)
3. Content collection schema (if using collections)
4. TypeScript types (for Props and data)
5. Brief explanation of hydration strategy chosen

## Technologies

Astro 6.x (Node 22+), Islands Architecture, Content Layer API (glob/file loaders, live content collections), Zod 4 Schemas (`astro/zod`), View Transitions API, Server Islands (`server:defer`), Sessions, Actions, Middleware, astro:env (type-safe environment variables), Content Security Policy (`security.csp`), Fonts API, i18n Routing, Adapters (Node, Vercel, Netlify, Cloudflare, Deno), React/Vue/Svelte/Solid integrations, Image Optimization, MDX, Markdoc, TypeScript, Scoped CSS, Tailwind CSS