Best practices for building modern, performant websites with Astro.

astro-ide-context-modern-rules.mdc

---
description: Best practices for building modern, performant websites with Astro.
globs: ["src/**/*.astro", "src/**/*.ts", "src/**/*.tsx"]
alwaysApply: false
---

# 🚀 Astro Modern Practices

## 🧠 Core Philosophy
- Island architecture: ship less JS by default.
- Prefer `.astro` files for content-driven UI.
- Use client components (`<Component client:load />`) only when needed.

## 🧱 Components
- Use `.astro` for static/UI-first components.
- Use React/Svelte/Vue only when interactivity is required.
- Pass props explicitly; no global state by default.

## 🌍 Routing
- File-based routing: `src/pages/about.astro` → `/about`.
- Use dynamic routes: `src/pages/blog/[slug].astro`.
- Add `404.astro` for custom not found pages.

## 📦 Content Collections
- Use `src/content/` + `defineCollection()` for blogs, docs, etc.
- Type-safe frontmatter with schemas.
- Prefer Markdown/MDX over pure `.astro` for content-heavy pages.

## 📄 SEO & Metadata
- Use `<title>`, `<meta>`, and Open Graph tags in layouts or pages.
- Generate sitemaps with `astro-sitemap`.
- Use canonical URLs, alt text, and semantic HTML.

## 🧩 Layouts
- Create base layouts in `src/layouts/`.
- Use `<slot />` and named slots for flexibility.
- Co-locate page layout with its route structure.

## 💨 Styling
- Use Tailwind CSS or scoped styles in `.astro` files.
- Use `:global()` only when absolutely needed.
- Prefer utility-first styling over long class chains.

## 🔌 Integrations
- Enable only what's needed: `@astrojs/image`, `@astrojs/mdx`, `@astrojs/sitemap`, etc.
- Configure integrations in `astro.config.mjs`.

## ⚙️ Scripts & Interactivity
- Prefer `client:load` or `client:visible` for progressive enhancement.
- Avoid unnecessary hydration (`client:only` for full islands).
- No hydration = no bundle — default behavior is optimal.

## 🌍 Images & Assets
- Use `astro/assets` pipeline (`<Image src={...} />`) for optimization.
- Set responsive sizes and `alt` attributes.
- Use SVGs inline for icons when possible.

## 🏗 File Structure
- src/
- pages/ # routes
- components/ # UI units
- layouts/ # page scaffolds
- content/ # Markdown/MDX + schemas
- styles/ # Tailwind or global CSS
- lib/ # utils, fetchers

## 🧪 Testing
- Use Playwright for integration/E2E.
- Use Vitest for logic/components.
- Prefer testing rendered HTML/output over logic.

## 📈 Performance
- Use Lighthouse or Web Vitals tools.
- Keep JS usage minimal (Astro does it by default).
- Lazy-load images and hydrate only interactive elements.

## 🛡 Security
- Escape user-generated content (Markdown, forms).
- Use `Content-Security-Policy` headers.
- Avoid inline JS unless trusted and controlled.

## ♿ Accessibility
- Use semantic HTML.
- Test keyboard navigation and screen reader flow.
- Lint with `eslint-plugin-jsx-a11y` if using JSX components.