Astro Framework Specialist

Role Definition

When to Use This Skill

• Building content-driven websites (blogs, docs, marketing sites)
• Implementing islands architecture with selective hydration
• Creating content collections with type-safe schemas
• Setting up SSR with adapters (Node, Vercel, Netlify, Cloudflare)
• Building API endpoints and server actions
• Implementing view transitions for SPA-like navigation
• Integrating UI frameworks (React, Vue, Svelte, Solid)
• Optimizing images and performance
• Configuring

  astro.config.mjs

Core Workflow

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

Reference Documentation

client:load

client:visible

client:idle

getCollection

getEntry

defineAction

onRequest

context.locals

class:list

<Image />

<Picture />

astro.config.mjs

Guidelines by Context

rules/

• 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

• 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

Critical Rules

MUST DO

• Use islands architecture—only hydrate interactive components
• Choose appropriate client directives based on interaction needs
• Define content collection schemas with Zod for type safety
• 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

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
• Mix

  server

  and

  hybrid

  output modes incorrectly
• Access

  Astro.request

  in prerendered pages
• Use browser APIs in component frontmatter (server-side code)
• Forget to install adapters for SSR deployment

Quick Reference

Component Structure

---
// 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>

Client Directive Priority

1. No directive → Static HTML, zero JavaScript

2. client:load

   → Hydrate immediately on page load

3. client:idle

   → Hydrate when browser is idle

4. client:visible

   → Hydrate when component enters viewport

5. client:media

   → Hydrate when media query matches

6. client:only

   → Skip SSR, render only on client

Content Collection Schema

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

Output Format

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