), or island architecture concepts. This skill covers project setup, rendering modes (SSG/SSR/hybrid), SSR caching, SEO, layouts, templates, Vue island integration, content collections, data fetching, deployment, auth, performance, and troubleshooting.

# Astro Advanced Skill

This skill provides production-grade guidance for Astro projects — from initial scaffolding through deployment, caching, and performance tuning. It covers the patterns that actually matter in real projects and the mistakes that actually happen.

How to use this skill

• Read this file first for the core workflow and decision tree.
• Consult the reference files in references/ for deep dives on specific topics:

Core decision tree

When helping with an Astro project, follow this sequence:

1. Identify the rendering strategy first

• Pure static site (blog, docs, marketing)? → SSG (default). No adapter needed.
• Needs user-specific data, auth, or real-time content? → SSR with an adapter.
• Mostly static but a few dynamic pages? → Hybrid mode. Set output: 'static' in config and use export const prerender = false on dynamic pages.

2. Pick the right adapter

• Vercel → @astrojs/vercel (serverless or edge)
• Netlify → @astrojs/netlify
• Cloudflare Pages → @astrojs/cloudflare
• Self-hosted Node → @astrojs/node (standalone or middleware)

3. Set up integrations

# Common additions
npx astro add vue        # Vue islands
npx astro add tailwind   # Tailwind CSS
npx astro add mdx        # MDX support
npx astro add sitemap    # Auto sitemap generation

4. Establish content strategy

• Few pages, hand-authored → Regular .astro pages in /src/pages
• Blog/docs with structured content → Content collections with Zod schemas
• CMS-driven → Fetch at build time (SSG) or runtime (SSR)

5. Apply SEO from the start

• Create a reusable component for head tags
• Set up canonical URLs
• Add structured data (JSON-LD) for key pages
• Generate sitemap via @astrojs/sitemap

Key patterns to always follow

Layout pattern

---
// src/layouts/Base.astro
import SEO from '../components/SEO.astro';
const { title, description } = Astro.props;


  
    
  
  
    
    
    
  

Island pattern

The #1 Astro mistake: forgetting client: on a component that needs interactivity, then wondering why click handlers don't work.

SSR caching pattern

// In an SSR endpoint or page
return new Response(JSON.stringify(data), {
  headers: {
    "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
    "Content-Type": "application/json"
  }
});

• "Component doesn't do anything" → Missing client: directive
• Build fails after adding integration → Version mismatch, check package.json
• SSR returns 500 → Missing adapter or wrong output mode in config
• Broken links after deploy → Base path not set, or trailing slash mismatch
• Hydration mismatch errors → Server/client HTML differs (conditional rendering, dates, randomness)

File output conventions

When generating Astro project files:

• Always include the frontmatter fence (---) even if empty
• Use .astro extension for Astro components and pages
• Place pages in src/pages/, components in src/components/, layouts in src/layouts/
• Use TypeScript in frontmatter when the project uses TS
• Include astro.config.mjs with only the integrations and settings actually needed