--- name: astro description: | Astro web framework patterns for content-driven sites. Covers content collections with Zod schemas and loaders, island architecture with selective hydration directives, view transitions with ClientRouter, server-side and hybrid rendering modes, server islands, Astro DB with astro:db, middleware with onRequest, and framework integrations (React, Svelte, Vue). Use when building content-driven websites, configuring island hydration strategies, setting up view transitions, choosing between static and server rendering, integrating UI framework components, defining content collection schemas, or adding middleware. license: MIT metadata: author: oakoss version: '1.0' source: 'https://docs.astro.build' user-invocable: false --- # Astro ## Overview Astro is an **all-in-one web framework** for building fast, content-focused websites. It uses an islands architecture that ships zero JavaScript by default, hydrating only interactive components on demand. Components from React, Svelte, Vue, Solid, and Preact can coexist in a single project. **When to use:** Content-driven sites (blogs, docs, marketing), portfolios, e-commerce storefronts, any site where most pages are primarily static with isolated interactive regions. **When NOT to use:** Highly interactive single-page applications (dashboards, real-time collaboration tools), apps requiring full client-side routing with shared global state across all components. ## Quick Reference | Pattern | API / Directive | Key Points | | ---------------------- | ------------------------------------------------- | ----------------------------------------------------- | | Content collection | `defineCollection({ loader, schema })` | Zod schemas, glob/file loaders, type-safe queries | | Query collection | `getCollection('blog')` | Returns typed array, supports filter callback | | Single entry | `getEntry('blog', 'my-post')` | Fetch by collection name and entry ID | | Island (load) | `` | Hydrate immediately on page load | | Island (idle) | `` | Hydrate when browser is idle | | Island (visible) | `` | Hydrate when component enters viewport | | Island (media) | `` | Hydrate on media query match | | Island (client-only) | `` | Skip SSR, render only on client | | View transitions | `` | Add to ``, enables SPA-like navigation | | Persist state | `transition:persist` | Maintain island state across navigations | | Programmatic navigate | `navigate(href)` | Client-side navigation from scripts | | Static output | `output: 'static'` | Pre-render all pages at build time (default) | | Server output | `output: 'server'` | Server-render all pages on demand | | Hybrid (opt-in SSR) | `output: 'static'` + per-page `prerender = false` | Static by default, opt individual pages into SSR | | Hybrid (opt-in static) | `output: 'server'` + per-page `prerender = true` | SSR by default, opt individual pages into static | | Server islands | `` | Defer server rendering for dynamic content in static | | Middleware | `onRequest(context, next)` | Runs before every route, chain with `sequence()` | | Astro DB table | `defineTable({ columns })` | Type-safe SQL with column definitions | | Framework component | Import `.jsx` / `.svelte` / `.vue` | Auto-detected by file extension | | Integration | `astro add react` | CLI to add framework adapters and tools | | Render content | `const { Content } = await entry.render()` | Compile Markdown/MDX to component | | Dynamic routes | `getStaticPaths()` + collection query | Generate pages from collection entries | | API endpoint | `export const GET: APIRoute` | Server-rendered REST endpoints | | Shared island state | `nanostores` | Reactive state across framework boundaries | | Environment variables | `import.meta.env.PUBLIC_*` | `PUBLIC_` prefix for client-accessible vars | | Transition animation | `transition:animate="slide"` | `initial`, `fade`, `slide`, `none` | | Prefetch links | `data-astro-prefetch` | `hover`, `viewport`, `load`, or `false` | | Collection reference | `reference('authors')` | Type-safe cross-collection relations | | Script re-execution | `data-astro-rerun` | Re-run `