Astro

---
name: astro
description: "Covers Astro across supported versions: the islands architecture (selective hydration with client:load, client:idle, client:visible, client:media, client:only), Server Islands (server:defer for on-demand rendering in cached pages), Content Layer API (collections, loaders, Zod schemas, cross-references), multi-framework support (React, Vue, Svelte, Solid, Preact on the same page), rendering modes (static, server, per-page prerender), View Transitions (ClientRouter), Actions (type-safe server mutations with Zod), astro:env (type-safe environment variables), image optimization (astro:assets), SSR adapters (Node, Vercel, Cloudflare, Netlify), and nanostores for cross-island state. Use for \"Astro\", \"astro\", \"islands architecture\", \"client:load\", \"client:visible\", \"server:defer\", \"Content Collections\", \"astro.config\", \"Astro actions\", \"multi-framework\" questions."
license: MIT
---

# Astro

This skill covers Astro across all supported versions, including:

- Islands architecture: static HTML by default, selective hydration with `client:*` directives
- Server Islands: `server:defer` for on-demand server rendering in CDN-cached pages
- Content Layer API: collections, glob/file/custom loaders, Zod schemas, cross-references
- Multi-framework support: React, Vue, Svelte, Solid, Preact, Alpine on the same page
- Rendering modes: static (SSG), server (SSR), per-page `prerender` overrides
- View Transitions: `<ClientRouter />`, `transition:animate`, `transition:persist`
- Actions: type-safe server-side mutations with Zod validation
- `astro:env`: type-safe environment variables with client/server/secret segmentation
- Image optimization: `<Image />` and `<Picture />` from `astro:assets`
- SSR adapters: Node.js, Vercel, Cloudflare, Netlify
- Cross-island state: nanostores for sharing state between React, Vue, Svelte islands
- Markdown and MDX: Shiki syntax highlighting, remark/rehype plugins

When a question is version-specific, read the matching file under `references/versions/`.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request type:
   - **Troubleshooting** -- Load `references/diagnostics.md`
   - **Architecture / Design** -- Load `references/architecture.md`
   - **Best practices** -- Load `references/best-practices.md`
   - **Islands / Hydration** -- Load `references/patterns/islands.md`
   - **Content collections** -- Load `references/patterns/content-layer.md`
   - **Multi-framework** -- Load `references/patterns/multi-framework.md`
   - **Configuration** -- Reference `assets/astro.config.mjs`

2. **Identify version** -- Determine whether the user is on Astro 4 or 5. If unclear, assume 5. Version matters for Content Layer API (v5), Server Islands (v5), `astro:env` (v5), and `ClientRouter` naming (v5).

3. **Load context** -- Read the relevant reference file for deep knowledge.

4. **Analyze** -- Apply Astro-specific reasoning. Astro is static-first; default to zero JS. Only recommend client directives when interactivity is genuinely needed. Consider the islands model, not SPA patterns.

5. **Recommend** -- Provide actionable guidance with code examples. Prefer `.astro` components for static content, framework components only for interactive islands.

6. **Verify** -- Suggest validation steps (`astro build --verbose`, browser DevTools Network tab for JS payload).

## Core Expertise

### Islands Architecture

Astro renders every page as static HTML by default. Zero JavaScript ships unless a component is explicitly marked for hydration with a `client:*` directive. Each hydrated component is an independent island.

| Directive | When Hydration Runs | Use Case |
|---|---|---|
| `client:load` | Immediately on page load | Above-the-fold interactive UI |
| `client:idle` | When browser is idle | Non-critical widgets |
| `client:visible` | When element enters viewport | Below-fold components |
| `client:media="(query)"` | When CSS media query matches | Responsive-only components |
| `client:only="framework"` | Client-only, skips SSR | Components that cannot server-render |

```astro
---
import ReactChart from './ReactChart.jsx';
import SvelteMenu from './SvelteMenu.svelte';
---
<ReactChart client:load data={stats} />
<SvelteMenu client:visible />
<HeavyD3Widget client:only="react" />
```

A component without `client:*` renders as static HTML only -- no event handlers, no state, no JS.

### Server Islands (v5)

Solve the CDN caching problem: cache the page at the edge, render personalized parts on-demand.

```astro
---
import UserGreeting from './UserGreeting.astro';
---
<header>
  <UserGreeting server:defer>
    <span slot="fallback">Welcome!</span>
  </UserGreeting>
</header>
```

The page serves from cache immediately. The browser fetches each `server:defer` component via GET. Props are encrypted to prevent leakage. Use `ASTRO_KEY` for stable encryption across deployments.

### Content Layer API (v5)

All collections use a `loader`. Config in `src/content.config.ts`.

```typescript
import { defineCollection, z } from 'astro:content';
import { glob, file } from 'astro/loaders';

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

export const collections = { blog };
```

Query with `getCollection()` and `getEntry()` from `astro:content`.

### Multi-Framework

Multiple UI frameworks on the same page. Install via `npx astro add react svelte vue`.

```astro
---
import ReactSearch from '../components/SearchBar.jsx';
import SvelteToast from '../components/Toast.svelte';
import VueAccordion from '../components/Accordion.vue';
---
<ReactSearch client:load />
<SvelteToast client:visible />
<VueAccordion client:idle />
```

Share state across frameworks with nanostores. Only `.astro` files can import components from multiple frameworks.

### Rendering Modes

| `output` | Default Behavior | Override |
|---|---|---|
| `'static'` (default) | All pages pre-rendered | `export const prerender = false` |
| `'server'` | All pages SSR on-demand | `export const prerender = true` |

SSR requires an adapter: `npx astro add node` / `vercel` / `cloudflare` / `netlify`.

### View Transitions

```astro
---
import { ClientRouter } from 'astro:transitions';
---
<head>
  <ClientRouter />
</head>
```

`transition:animate="slide"`, `transition:name="hero"`, `transition:persist` for keeping state across navigations.

### Actions

Type-safe server-side mutations defined in `src/actions/index.ts`:

```typescript
import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';

export const server = {
  subscribe: defineAction({
    accept: 'json',
    input: z.object({ email: z.string().email() }),
    handler: async ({ email }) => {
      await db.users.create({ email });
      return { success: true };
    },
  }),
};
```

## Common Pitfalls

**1. Missing client directive**
Component renders as static HTML with no interactivity. Add the appropriate `client:*` directive.

**2. Islands too large**
Hydrating entire page sections wastes JS. Keep islands small and focused.

**3. Content config in wrong location**
Astro 5 uses `src/content.config.ts` (not `src/content/config.ts` from v4).

**4. Props not serializable for islands**
Functions and class instances cannot be passed as props to client islands. Use plain objects, arrays, and primitives.

**5. JSX pragma conflicts with multiple React-like frameworks**
Scope frameworks with `include: ['./src/react/**']` in integration config.

**6. `getStaticPaths` missing for dynamic routes**
Dynamic routes in static mode require `getStaticPaths()`. Or set `prerender = false`.

**7. `process is not defined` in client bundle**
Node.js APIs used in client code. Move to server-only context or use `import.meta.env`.

**8. Server Islands on static pages without adapter**
Server Islands require an SSR adapter even if the rest of the site is static.

## Version-Specific Guidance

| Version | Reference | What's version-specific |
|---|---|---|
| 5 | `references/versions/5.md` | Server Islands, Content Layer API, `astro:env`, `ClientRouter`, Actions |

## Reference Files

- `references/architecture.md` -- Islands, Server Islands, Content Layer, multi-framework, rendering modes
- `references/best-practices.md` -- Content collections, island strategy, SSR adapters, images
- `references/diagnostics.md` -- Build errors, hydration issues, content layer debugging

## Configuration References

- `assets/astro.config.mjs` -- Annotated configuration file

## Pattern Guides

- `references/patterns/islands.md` -- Client directives, server islands, hydration strategies
- `references/patterns/content-layer.md` -- Collections, loaders, schemas
- `references/patterns/multi-framework.md` -- Mixing React+Vue+Svelte, shared state