---
name: astro-framework
description: "Astro pages, layouts, content collections, hydration directives and integrations. Use when adding or changing Astro pages, components or content collections, or choosing a client: directive."
---

# Astro Framework

Docs: https://docs.astro.build

## Gotchas

- `public/` serves assets as-is; `src/assets/` goes through the build pipeline. Wrong folder = no optimization, or a broken import.
- Astro v5+ defines collections in `src/content.config.ts` (not `src/content/config.ts`) and requires an explicit `loader`, e.g. `glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' })`.
- Default is zero client JS. Ship JS only via a `client:*` directive, and pick the cheapest one that still works: `client:load` (critical), `client:idle` (deferred), `client:visible` (lazy), `client:media` (breakpoint-gated), `client:only` (last resort — skips SSR entirely, so no server-rendered HTML).
- `getStaticPaths()` is required for dynamic routes in static output; it does not run in `output: 'server'`.
- SSR needs both `output: 'server'` (or `'hybrid'`) *and* an adapter (`node`, `vercel`, `netlify`, `cloudflare`) in `astro.config.mjs`.
- Collection schemas are Zod — use `z.coerce.date()` for frontmatter dates, since raw frontmatter is a string.

## Layout

`src/pages/` (file-based routes), `layouts/`, `components/`, `content/`, `styles/`, `assets/`. API routes: export `GET`/`POST` from `src/pages/api/*.ts` returning `new Response(...)`. Type-safe mutations: `defineAction` in `src/actions/index.ts`.

## Add a collection

1. Declare it in `src/content.config.ts` via `defineCollection` + Zod schema; export from `collections`.
2. Add `src/content/<name>/` with one sample file.
3. Query with `getCollection('<name>', filterFn)`.
4. The build must exit zero — collection types are generated at build time, so type errors only surface after a build.

Integrations: `astro add react tailwind mdx sitemap` etc. — never hand-edit the integrations array.