- name
- astro-advanced
- description
- >
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 useexport const prerender = falseon 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 generation4. Establish content strategy
- Few pages, hand-authored → Regular
.astropages 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
outputmode 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
.astroextension for Astro components and pages - Place pages in
src/pages/, components insrc/components/, layouts insrc/layouts/ - Use TypeScript in frontmatter when the project uses TS
- Include
astro.config.mjswith only the integrations and settings actually needed