/web-meta-framework-astro

name: web-meta-framework-astro
description: Astro content-first framework - islands architecture, content collections, file-based routing, SSR/SSG hybrid rendering, View Transitions, server islands, multi-framework component support

Astro Patterns

> **Quick Guide:** Astro renders pages to static HTML with zero client JavaScript by default. `.astro` > components carry static content; framework components become interactive islands only when given a > `client:*` directive. Content collections give structured Markdown type-safe frontmatter through Zod > schemas. Rendering mode is per page: static unless `export const prerender = false`. Astro 6 replaced > `<ViewTransitions />` with `<ClientRouter />`, replaced `Astro.glob()` with `import.meta.glob()`, moved > `z` from `astro:content` to `astro/zod` (now Zod 4), requires string `getStaticPaths()` params, and > requires Node 22.12.0+.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — typed props, expressions, nested layouts, scoped vs global styles, script handling
• [examples/islands.md](examples/islands.md) — directive selection, `client:only`, multi-framework islands, server islands, cross-island state
• [examples/content.md](examples/content.md) — collection schemas, querying, rendering, references, custom loaders, live collections
• [examples/routing.md](examples/routing.md) — static and dynamic routes, rest params, pagination, on-demand routes, endpoints, 404
• [examples/integrations.md](examples/integrations.md) — framework integrations, View Transitions, persistence, animations, Starlight
• [reference.md](reference.md) — project layout, route priority, collection API, adapters, rendering checklist

---

Which path applies

• **Every page is static** — the default. No `output` setting and no adapter; dynamic routes need

`getStaticPaths()`. Follow [examples/routing.md](examples/routing.md).

• **A few pages need request-time data** — keep the default, add `export const prerender = false` to

those pages, and install a server adapter. Same file, plus the adapter table in [reference.md](reference.md).

• **Most pages need request-time data** — set `output: "server"` and opt individual pages back to

static with `export const prerender = true`.

---

<critical_requirements>

Before writing Astro code

**Leave pages static and add `export const prerender = false` only where the page reads request-time data.** Static is the default and is where the framework's speed comes from.

**Install a server adapter before any page opts out of prerendering.** Without one, a build containing `prerender = false` fails.

**Give a framework component a `client:*` directive when it needs to be interactive.** Without a directive it renders to static HTML and its event handlers never run.

**Define collections in `src/content.config.ts` with a Zod schema.** The schema validates frontmatter at build time and generates the types the queries return.

**Use `getStaticPaths()` for dynamic routes in static mode.** On-demand routes read `Astro.params` directly and need no such export.

</critical_requirements>

---

**Auto-detection:** Astro, .astro files, astro.config, islands architecture, client:load, client:visible, client:idle, client:only, client:media, server:defer, content collections, defineCollection, defineLiveCollection, getCollection, getLiveCollection, getEntry, getLiveEntry, render, astro:content, astro:transitions, ClientRouter, getStaticPaths, Astro.props, Astro.params, Astro.cookies, Astro.redirect, prerender, astro add, @astrojs/react, @astrojs/vue, @astrojs/svelte, Starlight

**Applies to:**

• `.astro` component syntax — frontmatter, template expressions, slots, layouts, scoped styles
• Islands: client directives, hydration timing, server islands, mixing UI frameworks on one page
• Content collections: schemas, loaders, querying, rendering, cross-collection references
• File-based routing: static, dynamic, rest parameters, pagination, API endpoints
• Rendering mode: static, on-demand, and per-page `prerender` control
• View Transitions: `<ClientRouter />`, transition directives, persisted elements

**Handled elsewhere:**

• What an island renders internally — a hydrated component follows the conventions of whichever UI

library wrote it, and Astro settles only the boundary.

• Which CSS approach fills a `<style>` block — the scoping rules here are Astro's; the styling system is not.
• Which store library fills the cross-island seam — that islands share no tree, and that a module-scoped store is the way across, is settled in [examples/islands.md](examples/islands.md); which store you reach for is not.
• Fully interactive applications where every route is user-specific — that shape wants a framework

whose default is on-demand rendering rather than one whose default is static output.

---

<philosophy>

Astro is a **content-first framework that ships zero JavaScript by default**. Most of a page is static HTML; small interactive "islands" hydrate independently, each paying only for itself.

Four consequences follow, and they explain most of the API:

1. **A component is static until told otherwise** — `client:*` is the opt-in, so the cost of interactivity is always visible at the call site. 2. **The UI library is a detail** — React, Vue, Svelte, Solid and Preact components are all just island contents, and one page can carry several. 3. **Content is typed data** — collections put a Zod schema between Markdown frontmatter and the code that reads it, so a typo in a post fails the build rather than the page. 4. **Rendering mode is per page** — static and on-demand pages coexist in one project, which is why `prerender` is an export rather than a global setting.

</philosophy>

---

<decision_framework>

**Static or on-demand?** A page needs on-demand rendering when it reads cookies, headers or user-specific data at request time, or when its data changes faster than you are willing to rebuild. Everything