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

1. Read this file first for the core workflow and decision tree.
2. Consult the reference files in references/ for deep dives on specific topics:
   • references/setup-and-structure.md — Project creation, file structure, config, adapters
   • references/rendering-modes.md — SSG vs SSR vs Hybrid, when to use each, caching strategies
   • references/seo.md — Meta tags, Open Graph, JSON-LD, sitemaps, canonical URLs
   • references/islands-and-vue.md — Island architecture, client directives, Vue/React/Svelte integration
   • references/content-and-data.md — Content collections, data fetching, dynamic routes
   • references/deployment.md — Adapters, static hosts, serverless, environment variables
   • references/performance.md — Image optimization, bundle analysis, hydration control
   • references/troubleshooting.md — Common errors and fixes organized by symptom

Core decision tree

When helping with an Astro project, follow this sequence:

1. Identify the rendering strategy first

This is the single most important decision in any Astro project. Everything else flows from it.

• 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

Only needed for SSR or hybrid:

• 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

Add only what you need. Each integration is a potential build-time dependency:

# 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

Don't bolt it on later. See references/seo.md for the full pattern, but at minimum:

• Create a reusable \x3CSEO> 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

Every page should use a layout. Layouts handle \x3Chtml>, \x3Chead>, and shared chrome:

---
// src/layouts/Base.astro
import SEO from '../components/SEO.astro';
const { title, description } = Astro.props;
---
\x3Chtml lang="en">
  \x3Chead>
    \x3CSEO title={title} description={description} />
  \x3C/head>
  \x3Cbody>
    \x3Cnav>\x3C!-- shared nav -->\x3C/nav>
    \x3Cslot />
    \x3Cfooter>\x3C!-- shared footer -->\x3C/footer>
  \x3C/body>
\x3C/html>

Island pattern

Static by default. Only hydrate what needs interactivity:

\x3C!-- Static: renders HTML, ships zero JS -->
\x3CCard title="Hello" />

\x3C!-- Interactive: hydrates on load -->
\x3CCounter client:load />

\x3C!-- Interactive: hydrates when visible (lazy) -->
\x3CImageGallery client:visible />

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

SSR caching pattern

SSR without caching is just a slow website. Always pair SSR with a caching strategy:

// 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"
  }
});

When things go wrong

Read references/troubleshooting.md for a symptom-based guide. The top 5 issues:

1. "Component doesn't do anything" → Missing client:* directive
2. Build fails after adding integration → Version mismatch, check package.json
3. SSR returns 500 → Missing adapter or wrong output mode in config
4. Broken links after deploy → Base path not set, or trailing slash mismatch
5. 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