|
| 1 | +--- |
| 2 | +description: 'Astro development standards and best practices for content-driven websites' |
| 3 | +applyTo: '**/*.astro, **/*.ts, **/*.js, **/*.md, **/*.mdx' |
| 4 | +--- |
| 5 | + |
| 6 | +# Astro Development Instructions |
| 7 | + |
| 8 | +Instructions for building high-quality Astro applications following the content-driven, server-first architecture with modern best practices. |
| 9 | + |
| 10 | +## Project Context |
| 11 | +- Astro 5.x with Islands Architecture and Content Layer API |
| 12 | +- TypeScript for type safety and better DX with auto-generated types |
| 13 | +- Content-driven websites (blogs, marketing, e-commerce, documentation) |
| 14 | +- Server-first rendering with selective client-side hydration |
| 15 | +- Support for multiple UI frameworks (React, Vue, Svelte, Solid, etc.) |
| 16 | +- Static site generation (SSG) by default with optional server-side rendering (SSR) |
| 17 | +- Enhanced performance with modern content loading and build optimizations |
| 18 | + |
| 19 | +## Development Standards |
| 20 | + |
| 21 | +### Architecture |
| 22 | +- Embrace the Islands Architecture: server-render by default, hydrate selectively |
| 23 | +- Organize content with Content Collections for type-safe Markdown/MDX management |
| 24 | +- Structure projects by feature or content type for scalability |
| 25 | +- Use component-based architecture with clear separation of concerns |
| 26 | +- Implement progressive enhancement patterns |
| 27 | +- Follow Multi-Page App (MPA) approach over Single-Page App (SPA) patterns |
| 28 | + |
| 29 | +### TypeScript Integration |
| 30 | +- Configure `tsconfig.json` with recommended v5.0 settings: |
| 31 | +```json |
| 32 | +{ |
| 33 | + "extends": "astro/tsconfigs/base", |
| 34 | + "include": [".astro/types.d.ts", "**/*"], |
| 35 | + "exclude": ["dist"] |
| 36 | +} |
| 37 | +``` |
| 38 | +- Types auto-generated in `.astro/types.d.ts` (replaces `src/env.d.ts`) |
| 39 | +- Run `astro sync` to generate/update type definitions |
| 40 | +- Define component props with TypeScript interfaces |
| 41 | +- Leverage auto-generated types for content collections and Content Layer API |
| 42 | + |
| 43 | +### Component Design |
| 44 | +- Use `.astro` components for static, server-rendered content |
| 45 | +- Import framework components (React, Vue, Svelte) only when interactivity is needed |
| 46 | +- Follow Astro's component script structure: frontmatter at top, template below |
| 47 | +- Use meaningful component names following PascalCase convention |
| 48 | +- Keep components focused and composable |
| 49 | +- Implement proper prop validation and default values |
| 50 | + |
| 51 | +### Content Collections |
| 52 | + |
| 53 | +#### Modern Content Layer API (v5.0+) |
| 54 | +- Define collections in `src/content.config.ts` using the new Content Layer API |
| 55 | +- Use built-in loaders: `glob()` for file-based content, `file()` for single files |
| 56 | +- Leverage enhanced performance and scalability with the new loading system |
| 57 | +- Example with Content Layer API: |
| 58 | +```typescript |
| 59 | +import { defineCollection, z } from 'astro:content'; |
| 60 | +import { glob } from 'astro/loaders'; |
| 61 | + |
| 62 | +const blog = defineCollection({ |
| 63 | + loader: glob({ pattern: '**/*.md', base: './src/content/blog' }), |
| 64 | + schema: z.object({ |
| 65 | + title: z.string(), |
| 66 | + pubDate: z.date(), |
| 67 | + tags: z.array(z.string()).optional() |
| 68 | + }) |
| 69 | +}); |
| 70 | +``` |
| 71 | + |
| 72 | +#### Legacy Collections (backward compatible) |
| 73 | +- Legacy `type: 'content'` collections still supported via automatic glob() implementation |
| 74 | +- Migrate existing collections by adding explicit `loader` configuration |
| 75 | +- Use type-safe queries with `getCollection()` and `getEntry()` |
| 76 | +- Structure content with frontmatter validation and auto-generated types |
| 77 | + |
| 78 | +### View Transitions & Client-Side Routing |
| 79 | +- Enable with `<ClientRouter />` component in layout head (renamed from `<ViewTransitions />` in v5.0) |
| 80 | +- Import from `astro:transitions`: `import { ClientRouter } from 'astro:transitions'` |
| 81 | +- Provides SPA-like navigation without full page reloads |
| 82 | +- Customize transition animations with CSS and view-transition-name |
| 83 | +- Maintain state across page navigations with persistent islands |
| 84 | +- Use `transition:persist` directive to preserve component state |
| 85 | + |
| 86 | +### Performance Optimization |
| 87 | +- Default to zero JavaScript - only add interactivity where needed |
| 88 | +- Use client directives strategically (`client:load`, `client:idle`, `client:visible`) |
| 89 | +- Implement lazy loading for images and components |
| 90 | +- Optimize static assets with Astro's built-in optimization |
| 91 | +- Leverage Content Layer API for faster content loading and builds |
| 92 | +- Minimize bundle size by avoiding unnecessary client-side JavaScript |
| 93 | + |
| 94 | +### Styling |
| 95 | +- Use scoped styles in `.astro` components by default |
| 96 | +- Implement CSS preprocessing (Sass, Less) when needed |
| 97 | +- Use CSS custom properties for theming and design systems |
| 98 | +- Follow mobile-first responsive design principles |
| 99 | +- Ensure accessibility with semantic HTML and proper ARIA attributes |
| 100 | +- Consider utility-first frameworks (Tailwind CSS) for rapid development |
| 101 | + |
| 102 | +### Client-Side Interactivity |
| 103 | +- Use framework components (React, Vue, Svelte) for interactive elements |
| 104 | +- Choose the right hydration strategy based on user interaction patterns |
| 105 | +- Implement state management within framework boundaries |
| 106 | +- Handle client-side routing carefully to maintain MPA benefits |
| 107 | +- Use Web Components for framework-agnostic interactivity |
| 108 | +- Share state between islands using stores or custom events |
| 109 | + |
| 110 | +### API Routes and SSR |
| 111 | +- Create API routes in `src/pages/api/` for dynamic functionality |
| 112 | +- Use proper HTTP methods and status codes |
| 113 | +- Implement request validation and error handling |
| 114 | +- Enable SSR mode for dynamic content requirements |
| 115 | +- Use middleware for authentication and request processing |
| 116 | +- Handle environment variables securely |
| 117 | + |
| 118 | +### SEO and Meta Management |
| 119 | +- Use Astro's built-in SEO components and meta tag management |
| 120 | +- Implement proper Open Graph and Twitter Card metadata |
| 121 | +- Generate sitemaps automatically for better search indexing |
| 122 | +- Use semantic HTML structure for better accessibility and SEO |
| 123 | +- Implement structured data (JSON-LD) for rich snippets |
| 124 | +- Optimize page titles and descriptions for search engines |
| 125 | + |
| 126 | +### Image Optimization |
| 127 | +- Use Astro's `<Image />` component for automatic optimization |
| 128 | +- Implement responsive images with proper srcset generation |
| 129 | +- Use WebP and AVIF formats for modern browsers |
| 130 | +- Lazy load images below the fold |
| 131 | +- Provide proper alt text for accessibility |
| 132 | +- Optimize images at build time for better performance |
| 133 | + |
| 134 | +### Data Fetching |
| 135 | +- Fetch data at build time in component frontmatter |
| 136 | +- Use dynamic imports for conditional data loading |
| 137 | +- Implement proper error handling for external API calls |
| 138 | +- Cache expensive operations during build process |
| 139 | +- Use Astro's built-in fetch with automatic TypeScript inference |
| 140 | +- Handle loading states and fallbacks appropriately |
| 141 | + |
| 142 | +### Build & Deployment |
| 143 | +- Optimize static assets with Astro's built-in optimizations |
| 144 | +- Configure deployment for static (SSG) or hybrid (SSR) rendering |
| 145 | +- Use environment variables for configuration management |
| 146 | +- Enable compression and caching for production builds |
| 147 | + |
| 148 | +## Key Astro v5.0 Updates |
| 149 | + |
| 150 | +### Breaking Changes |
| 151 | +- **ClientRouter**: Use `<ClientRouter />` instead of `<ViewTransitions />` |
| 152 | +- **TypeScript**: Auto-generated types in `.astro/types.d.ts` (run `astro sync`) |
| 153 | +- **Content Layer API**: New `glob()` and `file()` loaders for enhanced performance |
| 154 | + |
| 155 | +### Migration Example |
| 156 | +```typescript |
| 157 | +// Modern Content Layer API |
| 158 | +import { defineCollection, z } from 'astro:content'; |
| 159 | +import { glob } from 'astro/loaders'; |
| 160 | + |
| 161 | +const blog = defineCollection({ |
| 162 | + loader: glob({ pattern: '**/*.md', base: './src/content/blog' }), |
| 163 | + schema: z.object({ title: z.string(), pubDate: z.date() }) |
| 164 | +}); |
| 165 | +``` |
| 166 | + |
| 167 | +## Implementation Guidelines |
| 168 | + |
| 169 | +### Development Workflow |
| 170 | +1. Use `npm create astro@latest` with TypeScript template |
| 171 | +2. Configure Content Layer API with appropriate loaders |
| 172 | +3. Set up TypeScript with `astro sync` for type generation |
| 173 | +4. Create layout components with Islands Architecture |
| 174 | +5. Implement content pages with SEO and performance optimization |
| 175 | + |
| 176 | +### Astro-Specific Best Practices |
| 177 | +- **Islands Architecture**: Server-first with selective hydration using client directives |
| 178 | +- **Content Layer API**: Use `glob()` and `file()` loaders for scalable content management |
| 179 | +- **Zero JavaScript**: Default to static rendering, add interactivity only when needed |
| 180 | +- **View Transitions**: Enable SPA-like navigation with `<ClientRouter />` |
| 181 | +- **Type Safety**: Leverage auto-generated types from Content Collections |
| 182 | +- **Performance**: Optimize with built-in image optimization and minimal client bundles |
0 commit comments