astro
npx skills add https://github.com/briantbr/astro-best-practices --skill astro
Agent 安装分布
Skill 文档
Astro Framework
Astro 5.x framework for building fast, content-focused websites with Islands Architecture and zero JavaScript by default.
Core Principles
1. Zero JavaScript by Default
Astro ships ZERO JavaScript unless you explicitly add a client directive.
<!-- Static HTML (no JS) -->
<Header />
<Footer />
<!-- Interactive island (JS loaded) -->
<Counter client:idle />
Rule: Only use client directives when components need hooks, state, or browser APIs.
2. Client Directives
| Directive | When to Use | Behavior |
|---|---|---|
client:load |
Critical interaction needed immediately | Hydrates on page load |
client:idle |
Non-critical interactivity | Hydrates when browser idle |
client:visible |
Below the fold content | Hydrates when scrolled into view |
client:media="(query)" |
Responsive components | Hydrates when media query matches |
client:only="framework" |
Breaks during SSR | Skips SSR, client-only render |
Decision tree: Needs immediate interaction? â client:load | Non-critical? â client:idle | Below fold? â client:visible | Only on mobile/desktop? â client:media | Breaks SSR? â client:only
3. Multi-Framework Support
Mix React, Vue, Svelte in the same project:
npx astro add react vue svelte
---
import ReactForm from './Form.jsx';
import VueChart from './Chart.vue';
import SvelteCounter from './Counter.svelte';
---
<ReactForm client:idle />
<VueChart client:visible />
<SvelteCounter client:load />
Quick Start
npm create astro@latest my-project
cd my-project
npx astro add tailwind react
npm run dev
Project Structure
src/
âââ components/ # .astro, .jsx, .vue, .svelte
âââ layouts/ # Page layouts
âââ pages/ # File-based routing
â âââ blog/[slug].astro
âââ content/ # Content Collections (Markdown/MDX)
â âââ blog/ # Collection folders
âââ styles/ # Global CSS
âââ content.config.ts # Content collections schema (Astro 5+)
Configuration
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import react from '@astrojs/react';
export default defineConfig({
site: 'https://example.com',
output: 'static', // or 'server'
integrations: [tailwind(), react()],
});
Output modes (Astro 5):
static– Blog, docs, marketing (default). Useexport const prerender = falsefor SSR pages.server– All pages SSR (requires adapter)
Astro 5 Change:
output: 'hybrid'was removed. The hybrid behavior is now the default instaticmode.
View Transitions
Enable SPA-like navigation with the Client Router:
---
import { ClientRouter } from 'astro:transitions';
---
<html>
<head>
<ClientRouter />
</head>
<body><slot /></body>
</html>
Note: In Astro 5, ViewTransitions was renamed to ClientRouter.
Commands
npm run dev # Start dev server (localhost:4321)
npm run build # Build for production
npm run preview # Preview production build
npx astro check # TypeScript checks
Core Patterns
Organized by priority – load on-demand as needed:
High Priority (Common Use Cases)
- Content Collections – Type-safe CMS for Markdown/MDX
- Image Optimization – Built-in Image and Picture components
- Server-Side Rendering – Dynamic routes, cookies, headers
- API Endpoints – Server-side API routes, RSS, sitemap
Medium Priority (Specific Features)
- Middleware – Request interception for auth, logging
- Pagination – Paginate large collections
- Environment & Config – Environment variables, TypeScript helpers
Low Priority (Advanced)
- Custom Integrations – Extend Astro’s build process
Real-World Recipes
Complete examples for common scenarios:
- Blog Setup – Full blog with tags, RSS, layouts
- Multi-Step Forms – React form with API integration
- Authentication – Cookie-based auth with protected routes
- SEO – Open Graph, Twitter Cards, structured data
- i18n – Multi-language support
- Dark Mode – Theme toggle with localStorage
External Resources
- Official Documentation: https://docs.astro.build
- Islands Architecture: https://docs.astro.build/en/concepts/islands/
- Client Directives: https://docs.astro.build/en/reference/directives-reference/#client-directives