Sheshiyer 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 (declareserver/client, secret/public). Use it instead of rawimport.meta.envfor 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:envfor secrets; actions over ad-hoc API routes. - Adapter major aligned to Astro major; none for static.
- Re-init scripts across view transitions.