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:
- 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 <SEO> 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 <html>, <head>, and shared chrome:

---
// src/layouts/Base.astro
import SEO from '../components/SEO.astro';
const { title, description } = Astro.props;
---
<html lang="en">
  <head>
    <SEO title={title} description={description} />
  </head>
  <body>
    <nav><!-- shared nav --></nav>
    <slot />
    <footer><!-- shared footer --></footer>
  </body>
</html>

Island pattern

Static by default. Only hydrate what needs interactivity:

<!-- Static: renders HTML, ships zero JS -->
<Card title="Hello" />

<!-- Interactive: hydrates on load -->
<Counter client:load />

<!-- Interactive: hydrates when visible (lazy) -->
<ImageGallery 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:

"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

astro-advanced

Safety Notice

Copy this and send it to your AI assistant to learn