TypeScript Astro Agent Rules
Project Context
- Use Astro 5+ with TypeScript strict mode enabled in `tsconfig.json`.
- Use content collections with Zod schemas for all structured content.
- Target zero-JavaScript static output by default; use islands only for interactive components.
- Choose one UI framework per project (React, Svelte, or Vue) to minimize client bundle size.
Code Style & Structure
- Use TypeScript in all `.astro` component frontmatter scripts and utility modules.
- Declare typed `interface Props` in every component that accepts props via `Astro.props`.
- Name utilities with camelCase, components with PascalCase, and page files in kebab-case.
- Keep frontmatter scripts focused — fetch data and compute values; extract complex logic to `src/lib/`.
- Use named exports for utilities and default exports only for page components.
Astro Components
- Write `.astro` components for all static content — they produce zero client JavaScript.
- Use `<slot />` for composition and named slots (`<slot name="header" />`) for multi-zone layouts.
- Use `set:html` directive only for trusted, pre-sanitized HTML content.
- Pass serializable props only across island boundaries — no functions, no complex class instances.
- Use `Astro.url` for canonical URL generation and `Astro.site` for absolute URL construction.
Islands Architecture
- Use `client:load` for components that must be interactive on initial page load.
- Use `client:visible` for below-the-fold interactive components to defer hydration until visible.
- Use `client:idle` for non-critical widgets that can wait until the browser is idle.
- Use `client:media="(min-width: 1024px)"` for components that should only hydrate on certain viewports.
- Never add `client:*` to components that have no interactive behavior — static is always the default.
Content Collections
- Define all collections in `src/content/config.ts` with `defineCollection` and explicit Zod schemas.
- Use `z.date()` for frontmatter dates, `z.string().url()` for URLs, `z.enum([...])` for category fields.
- Use `reference()` for typed cross-collection relationships (post referencing author by ID).
- Generate pages from collections with `getStaticPaths()` in `[slug].astro` dynamic route files.
- Validate all frontmatter at build time — Astro throws on schema violations before the site is built.
Data Fetching
- Fetch external API data in frontmatter at build time for static pages — cache responses where possible.
- For SSR routes, wrap `fetch` calls in try/catch and return appropriate error responses.
- Define API routes in `src/pages/api/` returning `Response` objects — use `context.request` for input.
- Use `Astro.response.headers.set('Cache-Control', '...')` to configure CDN caching on SSR pages.
View Transitions
- Import `<ViewTransitions />` from `astro:transitions` and place it in `<head>` of the base layout.
- Assign `transition:name="unique-id"` to shared elements that should animate between pages.
- Use `transition:animate="slide"` or `"fade"` for directional page transitions.
- Handle JavaScript state cleanup on transition with `astro:before-swap` and `astro:after-swap` events.
SEO & Meta
- Define a `<BaseHead>` component that sets charset, viewport, canonical URL, and Open Graph tags.
- Generate `sitemap.xml` with `@astrojs/sitemap` — configure `site` URL in `astro.config.mjs`.
- Add JSON-LD structured data in page frontmatter for articles, products, and breadcrumbs.
- Set `<title>` and `<meta name="description">` on every page — never leave them empty or duplicated.
Performance
- Use `<Image />` from `astro:assets` for all images — automatic WebP conversion, sizing, and lazy loading.
- Inline critical CSS by default — Astro scopes component styles and inlines them during build.
- Audit builds with Lighthouse CLI in CI — target 95+ for Performance, Accessibility, and SEO scores.
- Use `prefetch` on anticipated navigation links — configure globally in `astro.config.mjs`.
Testing
- Test utility functions and Zod schemas with Vitest.
- Test API routes by constructing `Request` objects and asserting on `Response` values.
- Validate that all `getStaticPaths` paths are generated correctly by inspecting the returned params array.
- Run `astro check` in CI to catch TypeScript errors in frontmatter scripts before deployment.
TypeScript/
Astro