Cursor plugin for Astro containing tools to assist you during development including the official Astro Docs MCP, rules with best practises and coding standards and several skills such as add integration, content collection, create component, docs lookup and migrate.
# Astro Best Practices
## Core Principles
- Prefer static generation (SSG) over server-side rendering when possible
- Use partial hydration with `client:*` directives only when JavaScript is required
- Keep client-side JavaScript minimal for optimal performance
- Follow Astro's file-based routing conventions
## Project Structure
```
src/content.config.ts # Build-time content collection definitions
src/
├── components/ # Reusable UI components (.astro, .tsx, .vue)
├── layouts/ # Page layouts with common structure
├── pages/ # File-based routes
├── content/ # Content entries (Markdown/MDX)
├── styles/ # Global styles
└── assets/ # Processed assets (images, fonts)
public/ # Static assets (served as-is)
```
## Components
- Use `.astro` components for static content (zero JS by default)
- Reserve framework components (React, Vue, Svelte) for interactive features
- Apply client directives strategically:
- `client:load` - Critical interactivity needed immediately
- `client:idle` - Lower priority, load when browser is idle
- `client:visible` - Load when component enters viewport
- `client:media` - Load based on media query
- `client:only` - Skip server render entirely
## Content Collections
- Define collections in `src/content.config.ts`
- Use loaders and Zod schemas for type-safe content
- Use `getCollection()` and `getEntry()` for querying
- Use `render(entry)` instead of relying on legacy `entry.render()`
- Leverage frontmatter for metadata
- Prefer MDX for content requiring components
## Performance
- Use `<Image />` component for automatic optimization
- Implement view transitions and client routing with `<ClientRouter />` when appropriate
- Minimize layout shifts with proper image dimensions
- Use content collections for large content sites
## Accessibility
- Use semantic HTML elements (`<nav>`, `<main>`, `<article>`, etc.)
- Ensure keyboard navigation works for all interactive elements
- Provide alt text for images (or `alt=""` for decorative images)
- Maintain proper heading hierarchy (h1 → h6)
- Test with screen readers and keyboard-only navigation
## Data Fetching
- Fetch data in component frontmatter (server-side by default)
- Use `Astro.props` for component data passing
- Implement `getStaticPaths()` for dynamic routes in SSG mode
- Consider API routes for server-side endpoints
## Styling
- Scoped styles are default in `.astro` components
- Use `is:global` directive sparingly for global styles
- Prefer CSS custom properties for theming
- Support dark mode with `prefers-color-scheme` or class-based toggle
## Common Patterns
```astro
---
// Frontmatter: runs at build time (SSG) or request time (SSR)
import Layout from '../layouts/Layout.astro'
import { getCollection } from 'astro:content'
const posts = await getCollection('blog')
---
<Layout title="Blog">
<main>
{posts.map(post => (
<article>
<h2>{post.data.title}</h2>
</article>
))}
</main>
</Layout>
<style>
/* Scoped by default */
article {
padding: 1rem;
}
</style>
```