Astro

Pathrule2 Rules • 2 Memories • 1 Skill

A pattern bundle for Astro 5 projects built around islands architecture, the Content Layer API, and server islands. It keeps agents disciplined about partial hydration, schema-validated content, and the static-first render model so pages stay fast and predictable. Use it for content-driven sites, marketing pages, docs, and blogs that mix static output with a few interactive islands.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

astro-review

src/

View Transitions and navigation polish without a framework

components/

Hydrate islands intentionally, never by reflex

content/

Define every collection with a loader and a Zod schema

pages/

Rendering modes: static by default, server islands for the dynamic bits

Rules

Hydrate islands intentionally, never by reflex/src/componentshighadvisoryEvery framework component stays static HTML unless a client:* directive proves it must be interactive.

1	Astro renders UI framework components to static HTML by default and ships zero JavaScript for them. A `client:*` directive is a performance contract, not boilerplate. Default to no directive and add the lightest one only when interaction is actually required.
2
3	- Reserve `client:load` for above-the-fold controls that must be interactive immediately. Use `client:visible` for below-the-fold widgets and `client:idle` for low-priority ones.
4	- Treat `client:only` as a last resort. It skips server rendering, hurts SEO, and removes the static HTML fallback.
5	- Split large interactive components so only the truly dynamic part hydrates, keeping the rest as static `.astro` markup.
6	- Pass a `rootMargin` to `client:visible` for heavy components to hydrate them just before they scroll into view and reduce layout shift.

Define every collection with a loader and a Zod schema/src/contenthighstrictContent lives in the Content Layer API with a loader and validated schema, never raw file reads.

1	In Astro 5 content collections use the Content Layer API. Each collection is declared in `src/content.config.ts` with an explicit `loader` and a Zod `schema`, so frontmatter is validated at build time and queries are fully typed.
2
3	- Use the built-in `glob()` or `file()` loader for local Markdown, MDX, JSON, and YAML. Use a custom or community loader for CMS, API, or database sources.
4	- Always give the collection a `schema` so `getCollection()` and `getEntry()` return typed, validated data and bad frontmatter fails the build.
5	- Query content only through `getCollection()` / `getEntry()`. Do not read files with `fs` or `import.meta.glob`.
6	- For very large stores, set `retainBody: false` on the loader to shrink the deployed data store and avoid size limits.

Memories

Rendering modes: static by default, server islands for the dynamic bits/src/pagesKeep pages prerendered and isolate personalized content into server:defer islands.

1	Astro pages are statically prerendered by default. Keep them that way so the shell can be cached aggressively, and push only the dynamic parts to the edges.
2
3	- Mark personalized or per-request fragments (avatar, cart, recommendations) with `server:defer` so they render in their own request without blocking the cached page.
4	- Provide a `slot="fallback"` for each server island so users see meaningful placeholder markup until the island resolves.
5	- Reach for full on-demand SSR (`export const prerender = false`) only when an entire route is dynamic. Prefer server islands on otherwise-static pages.
6	- Server islands need an SSR adapter configured, even when most of the site is static.

View Transitions and navigation polish without a framework/srcUse the native View Transitions API via the ClientRouter for smooth navigation.

1	Astro supports the native View Transitions API for animated, app-like navigation without adding a client-side framework. Add the `<ClientRouter />` component to a shared layout head to enable it site-wide.
2
3	- Persist stateful elements across navigations with `transition:persist` (for example a video player or audio element).
4	- Name matched elements with `transition:name` so Astro animates them between pages, and tune motion with `transition:animate`.
5	- The router enhances real navigations progressively. Pages still work as full document loads when the API is unavailable, so do not depend on it for correctness.
6	- Keep transitions subtle and respect `prefers-reduced-motion`; heavy animations undercut the speed Astro is chosen for.

Skills

astro-review/rootPre-merge checklist for Astro 5 pages, islands, and content collections.

1	---
2	name: astro-review
3	description: Review checklist for Astro 5 work covering hydration directives, the Content Layer API, server islands, rendering mode, and view transitions before merging.
4	---
5
6	# Astro review
7
8	- [ ] Framework components render static HTML by default; every `client:*` directive is justified and uses the lightest option (`visible`/`idle` over `load`).
9	- [ ] No stray `client:only` that drops server rendering and the static fallback.
10	- [ ] Content is read through `getCollection()` / `getEntry()`, never raw `fs` or `import.meta.glob`.
11	- [ ] Each collection in `src/content.config.ts` has an explicit `loader` and a Zod `schema`.
12	- [ ] Pages stay prerendered by default; `prerender = false` is used only for fully dynamic routes.
13	- [ ] Personalized fragments use `server:defer` with a `slot="fallback"`, and an SSR adapter is configured.
14	- [ ] Large content stores set `retainBody: false` when bodies are not needed at runtime.
15	- [ ] View Transitions go through `<ClientRouter />`; `transition:persist` and `transition:name` are applied where state or motion continuity matters.
16	- [ ] Animations respect `prefers-reduced-motion`.
17	- [ ] No unnecessary JavaScript shipped; the page works with scripts disabled where it reasonably should.

Why this pattern

Agents reach for client-side hydration and unvalidated content by default, bloating Astro pages with JavaScript and runtime errors.

Built for Teams building content-driven Astro sites: marketing pages, docs, blogs, and commerce fronts..

Keeps your assistant from:

Slapping client:load on every interactive component and shipping needless JavaScript
Reading content with raw fs or import.meta.glob instead of schema-validated content collections
Blocking the whole page on a slow personalized request instead of deferring it to a server island

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-06-09