Astro Best Practices Skill

This skill provides comprehensive guidance on Astro 5 best practices for building high-performance, production-ready web applications.

When to Invoke

Activate this skill automatically when:

• Working with .astro files or Astro components
• Configuring astro.config.mjs or astro.config.ts
• Implementing islands architecture with client:* directives
• Setting up content collections with schemas
• Optimizing images using Astro’s Image component
• Configuring SSG/SSR/hybrid rendering strategies
• Implementing view transitions
• Working with astro:env or environment variables
• Setting up middleware or API routes
• Discussing performance optimization in Astro projects

Quick Reference

Performance Impact Categories

Impact Level	When to Address	Example Consequences
CRITICAL	Before production deploy	80%+ JS bloat, 10x cost increase, failed Core Web Vitals
HIGH	During implementation	2-3s slower LCP, 3.6x build time, type errors in production
MEDIUM-HIGH	Code review phase	Bundle size issues, maintainability problems
MEDIUM	Nice to have	UX improvements, better DX
LOW-MEDIUM	Advanced optimization	Edge performance, advanced patterns

Section Overview

Section	Rules	Priority	Key Focus
1. Islands & Hydration	8	CRITICAL	Partial hydration, client directives, JS bundle optimization
2. Build Optimization	7	CRITICAL	SSG vs SSR, hybrid rendering, build performance
3. Content & Data Loading	7	HIGH	Content collections, schemas, data fetching patterns
4. Image & Asset Optimization	6	HIGH	LCP optimization, responsive images, asset strategy
5. Component Patterns	6	MEDIUM-HIGH	.astro vs framework components, composition
6. View Transitions	5	MEDIUM	SPA-like navigation, animation performance
7. Environment & Middleware	5	MEDIUM	Type-safe env vars, middleware patterns
8. Advanced Patterns	3	LOW-MEDIUM	Streaming SSR, edge middleware, advanced optimization

Critical Anti-Patterns to Avoid

These are the most common and impactful mistakes in Astro projects:

1. Using client:load everywhere - Eliminates all benefits of islands architecture (80%+ JS bloat)
2. Using SSR for static content - 10x higher hosting costs and slower response times
3. Skipping content collection schemas - Runtime errors and type safety issues in production
4. Not using the Image component - 2x slower LCP (3.2s → 1.6s typical improvement)
5. Wrapping entire layouts as islands - Creates massive hydration overhead
6. Client-side data fetching in .astro files - Breaks the build-time architecture model
7. Using client:only unnecessarily - Kills SEO and initial page render performance

Rule Categories

1. Islands & Hydration (CRITICAL)

Focus on partial hydration and JavaScript optimization. Incorrect usage can bloat bundles by 80%+ and eliminate Astro’s core performance benefits.

2. Build Optimization (CRITICAL)

SSG vs SSR decisions, hybrid rendering, and build performance. Wrong choices can lead to 10x higher hosting costs and significantly slower response times.

3. Content & Data Loading (HIGH)

Content collections, type safety with Zod schemas, and the Content Layer API. Proper patterns prevent runtime errors and enable 3.6x faster builds.

4. Image & Asset Optimization (HIGH)

Image component usage, responsive images, and asset strategy. Proper optimization typically improves LCP from 3.2s to 1.6s.

5. Component Patterns (MEDIUM-HIGH)

When to use .astro components vs framework components, composition patterns, and type safety strategies.

6. View Transitions (MEDIUM)

Implementing SPA-like navigation with minimal JavaScript, state persistence, and animation performance considerations.

7. Environment & Middleware (MEDIUM)

Type-safe environment variables with astro:env, middleware patterns, and security best practices.

8. Advanced Patterns (LOW-MEDIUM)

Streaming SSR, server islands, edge middleware, and advanced optimization techniques for high-traffic applications.

Integration with Claude Code

This skill is automatically available when working with Astro projects. To explicitly invoke:

Use astro-best-practices skill to review this code

Or reference specific sections:

Check islands hydration patterns against astro-best-practices

Performance Metrics Reference

Common improvements when following these best practices:

• JavaScript Bundle: 80%+ reduction with proper island usage
• LCP (Largest Contentful Paint): 3.2s → 1.6s with Image component
• Build Speed: 35 → 127 pages/second with optimization
• Hosting Costs: 10x reduction using SSG over SSR for static content
• Remote Data Fetching: 3.6x faster with Content Layer caching
• TTFB: 200ms → 50ms with proper SSG configuration

Reference Documentation

All rules link to official Astro 5 documentation:

• Islands Architecture: https://docs.astro.build/en/concepts/islands/
• Server-Side Rendering: https://docs.astro.build/en/guides/server-side-rendering/
• Content Collections: https://docs.astro.build/en/guides/content-collections/
• Images: https://docs.astro.build/en/guides/images/
• View Transitions: https://docs.astro.build/en/guides/view-transitions/
• Environment Variables: https://docs.astro.build/en/guides/environment-variables/

For complete rule details, see AGENTS.md in this directory.