---
name: astro-core
description: "Shared reference for the Astro cluster: the rendering-mode decision (static / on-demand SSR / hybrid + server islands), hydration directives, the Content Layer & collections model, astro:env / sessions / actions conventions, and SSR adapter selection. USE WHEN deciding how an Astro page renders or where data comes from — the cross-cutting model the Astro spokes share. Implementation depth lives in astro-framework."
cluster: astro
version: 1.0.0
---

# Astro Core

Shared model for the `astro` cluster. The rendering and content decisions below shape every
page; keep them consistent. For full implementation, see `astro-framework`.

## 1. Rendering mode (decide first)

| Need | Mode |
|---|---|
| Content known at build time (marketing, docs, blog) | **Static (SSG)** — the default; fastest, cheapest |
| Per-request data (auth, personalization, form POST) | **On-demand (SSR)** — set `export const prerender = false` on that route |
| Mostly static with a few dynamic fragments | **Static page + server islands** (`server:defer`) — render the shell statically, stream the dynamic piece |
| Mixed across the site | **Hybrid** — static by default, opt specific routes into SSR |

**Ship static by default; opt into SSR only where required.** Server islands keep a page static
while deferring a dynamic fragment — prefer them over making the whole route SSR.

## 2. Islands & hydration

Astro ships zero JS by default. A framework component is static HTML unless you add a directive:

- `client:load` — hydrate immediately (above-the-fold interactivity).
- `client:idle` — when the browser is idle (non-urgent).
- `client:visible` — when scrolled into view (best default for below-the-fold).
- `client:media` — when a media query matches.
- `client:only` — skip SSR, render only on the client (for client-only libs).

Keep islands small and hydrate at the **latest** directive that works.

## 3. Content (Content Layer & collections)

- **Content collections** under `src/content/` (or configured) with a schema (`zod`) for typed, validated content.
- **Content Layer loaders**: `glob()` / `file()` for local content; **live loaders** for data fetched at request time; custom loaders for any source.
- Query with `getCollection` / `getEntry`; render Markdown/MDX via the entry's component.
- Docs/wiki publishing flows → `astro-wiki-publisher`.

## 4. Server conventions

- **`astro:env`** — typed, validated environment variables (declare `server`/`client`, secret/public). Use it instead of raw `import.meta.env` for anything sensitive or required.
- **Sessions** — server-side session storage (with an SSR adapter) for per-user state.
- **Actions** — typed server functions callable from the client with input validation; prefer over hand-rolled API routes for form/RPC.

## 5. SSR adapters

On-demand rendering needs an adapter matched to the host: `@astrojs/vercel`, `@astrojs/cloudflare`,
`@astrojs/node`, etc. Match the adapter to the deploy target; align its major with the Astro major.
Static-only sites need **no** adapter.

## 6. View transitions

`<ClientRouter />` enables SML-like cross-page transitions. Scripts don't re-run on client nav —
re-init on `astro:page-load`; `transition:persist` keeps element state across navigation. (Animation
specifics → creative-frontend's `astro-gsap-scrolltrigger`.)

## 7. Shared guardrails

- Static-first; SSR only where needed; server islands for dynamic fragments in static pages.
- Minimal islands, latest-working hydration directive.
- Typed content schemas; `astro:env` for secrets; actions over ad-hoc API routes.
- Adapter major aligned to Astro major; none for static.
- Re-init scripts across view transitions.