astro

# Astro Development Instructions

Instructions for building high-quality Astro applications following the content-driven, server-first architecture with modern best practices.

Project Context

- Astro 5.x with Islands Architecture and Content Layer API

- TypeScript for type safety and better DX with auto-generated types

- Content-driven websites (blogs, marketing, e-commerce, documentation)

- Server-first rendering with selective client-side hydration

- Support for multiple UI frameworks (React, Vue, Svelte, Solid, etc.)

- Static site generation (SSG) by default with optional server-side rendering (SSR)

- Enhanced performance with modern content loading and build optimizations

Development Standards

Architecture

- Embrace the Islands Architecture: server-render by default, hydrate selectively

- Organize content with Content Collections for type-safe Markdown/MDX management

- Structure projects by feature or content type for scalability

- Use component-based architecture with clear separation of concerns

- Implement progressive enhancement patterns

- Follow Multi-Page App (MPA) approach over Single-Page App (SPA) patterns

TypeScript Integration

- Configure `tsconfig.json` with recommended v5.0 settings:

{
  "extends": "astro/tsconfigs/base",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

- Types auto-generated in `.astro/types.d.ts` (replaces `src/env.d.ts`)

- Run `astro sync` to generate/update type definitions

- Define component props with TypeScript interfaces

- Leverage auto-generated types for content collections and Content Layer API

Component Design

- Use `.astro` components for static, server-rendered content

- Import framework components (React, Vue, Svelte) only when interactivity is needed

- Follow Astro's component script structure: frontmatter at top, template below

- Use meaningful component names following PascalCase convention

- Keep components focused and composable

- Implement proper prop validation and default values

Content Collections

#### Modern Content Layer API (v5.0+)

- Define collections in `src/content.config.ts` using the new Content Layer API

- Use built-in loaders: `glob()` for file-based content, `file()` for single files

- Leverage enhanced performance and scalability with the new loading system

- Example with Content Layer API:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional()
  })
});

#### Legacy Collections (backward compatible)

- Legacy `type: 'content'` collections still supported via automatic glob() implementation

- Migrate existing collections by adding explicit `loader` configuration

- Use type-safe queries with `getCollection()` and `getEntry()`

- Structure content with frontmatter validation and auto-generated types

View Transitions & Client-Side Routing

- Enable with `<ClientRouter />` component in layout head (renamed from `<ViewTransitions />` in v5.0)

- Import from `astro:transitions`: `import { ClientRouter } from 'astro:transitions'`

- Provides SPA-like navigation without full page reloads

- Customize transition animations with CSS and view-transition-name

- Maintain state across page navigations with persistent islands

- Use `transition:persist` directive to preserve component state

Performance Optimization

- Default to zero JavaScript - only add interactivity where needed

- Use client directives strategically (`client:load`, `client:idle`, `client:visible`)

- Implement lazy loading for images and components

- Optimize static assets with Astro's built-in optimization

- Leverage Content Layer API for faster content loading and builds

- Minimize bundle size by avoiding unnecessary client-side JavaScript

Styling

- Use scoped styles in `.astro`