astro-framework-agents / astro-framework
AGENTS.md44 starsChanged 8 months agoMITView on GitHub
Version: 2.0.0 | Astro 5.x | Updated: 2026-03-22 | Author: webreactiva.com
1 other project uses a version of this.
Adopted by
Most recently taken up by
- midudev/la-velada-web-oficialword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- midudev/la-velada-web-oficial★ 1.9k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- skills/learning-astro/AGENTS.mdAGENTS.md
- astro-frameworkSkill
- learning-astroSkill
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 1 is common, 1 is distinctive, and 8 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 61
NEVER: use client:load on everything — defeats islands architecture
- Very specific: line 62
NEVER: use client:only without the framework string argument
- Very specific: line 63
NEVER: use plain z.date() for frontmatter dates — use z.coerce.date()
- Very specific: line 64
NEVER: use string paths for local images (src="/images/hero.jpg") — import them
- Distinctive: line 68
NEVER: use sessions in edge middleware or static pages
- Very specific: line 71
NEVER: use any — use unknown and narrow
- Very specific: line 72
NEVER: import Zod from zod — use astro/zod (Astro 5+)
- Very specific: line 90
Use Referer header inside island to get parent page URL
- Very specific: line 102
Import from astro:env/client or astro:env/server
- Common: line 104
No secret client vars — not supported by design
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Astro Framework Cheatsheet
Version: 2.0.0 | Astro 5.x | Updated: 2026-03-22 | Author: webreactiva.com
Quick Reference Card
| Topic | Rule of Thumb |
| Components | Define interface Props; frontmatter = server only; use class:list for conditional classes |
| Hydration | Default: no directive (zero JS). Question every client: |
| Server Islands | server:defer for personalized/dynamic server content on cached pages |
| Content Collections | Content Layer API with loaders in src/content.config.ts (NOT src/content/config.ts) |
| Rendering content | import { render } from 'astro:content' then const { Content } = await render(entry) |
| Routing | File-based; getStaticPaths() required for dynamic routes in static mode |
| Output modes | static (default), server (all SSR), hybrid (static default, opt-in SSR) |
| Sessions | Astro.session?.get/set; always use optional chaining; SSR only |
| Env vars | astro:env schema with envField for type safety; import from astro:env/client or astro:env/server |
| Images | Import local images; use <Image> / <Picture> from astro:assets; always set alt text |
| i18n | Use getRelativeLocaleUrl() for links, never hardcode locale prefixes |
| TypeScript | Extend astro/tsconfigs/strict; define path aliases; type App.Locals in src/env.d.ts |
| API routes | Export named handlers (GET, POST, etc.) typed as APIRoute |
Decision Trees
Output Mode
All static? ──> output: 'static' (default, no adapter)
All dynamic? ──> output: 'server' + adapter
Mix? ──> output: 'hybrid' + adapter
Opt into SSR (hybrid): export const prerender = false
Opt out of SSR (server): export const prerender = trueHydration Directive
Needs interactivity?
├─ No ──> No directive (zero JS)
└─ Yes ──> Above fold + critical? ──> client:load
Above fold + non-critical? ──> client:idle
Below fold? ──> client:visible
Device-specific? ──> client:media="(query)"
Browser APIs only, skip SSR? ──> client:only="react"Server Island vs Client Island
Needs server data (cookies, DB, personalization)? ──> server:defer + slot="fallback"
Needs browser interactivity? ──> client:* directive
Neither? ──> Static .astro componentCritical "NEVER Do" List
- NEVER access
window/documentin.astrofrontmatter (server-only) - NEVER use
client:loadon everything — defeats islands architecture - NEVER use
client:onlywithout the framework string argument - NEVER use plain
z.date()for frontmatter dates — usez.coerce.date() - NEVER use string paths for local images (
src="/images/hero.jpg") — import them - NEVER access
Astro.request/Astro.cookies/Astro.sessionin prerendered pages - NEVER rely on
Astro.urlinside a server island (returns internal route; useRefererheader) - NEVER pass large objects/functions as server island props (IDs only; >2048 bytes forces POST)
- NEVER use sessions in edge middleware or static pages
- NEVER forget
getStaticPaths()for[param]routes in static output - NEVER skip
slot="fallback"onserver:defercomponents - NEVER use
any— useunknownand narrow - NEVER import Zod from
zod— useastro/zod(Astro 5+)
Astro 5+ Migration Notes (Post-Training Knowledge)
Content Collections (Content Layer API)
- Config file:
src/content.config.ts(wassrc/content/config.ts) - Uses
loaderproperty instead oftype: 'content'/type: 'data' - Loaders:
import { glob, file } from 'astro/loaders' - Zod:
import { z } from 'astro/zod'(NOT fromzodpackage) - Rendering:
import { render } from 'astro:content'thenawait render(entry)(wasentry.render()) reference()for cross-collection relationships;image()schema helper for optimized images
server:defer (Stable in Astro 5)
- Requires adapter; props must be serializable and small
- Use
Refererheader inside island to get parent page URL
Sessions (Astro 5.7+)
Astro.session?.get(key)/.set(key, value)— always optional-chain- Configure
session.driverin config viasessionDriversfromastro/config session.regenerate()after login,session.destroy()on logout- Type via
App.SessionDatainsrc/env.d.ts
astro:env (Stable in Astro 5)
- Schema in
astro.config.mjswithenvFieldfromastro/config - Import from
astro:env/clientorastro:env/server - Three kinds: public client (bundled), public server (server bundle), secret server (not bundled)
- No secret client vars — not supported by design
Actions
defineActionfromastro:actionswithastro/zodschemas
Key Patterns (Brief)
- Component structure: imports,
interface Props, destructure with defaults, logic, template, scoped<style> - Slots:
Astro.slots.has('name')to conditionally render named slot wrappers - Middleware:
defineMiddlewarefromastro:middleware; chain withsequence(a, b); file:src/middleware.ts - Pagination:
getStaticPaths({ paginate })returnspage.data,page.url.prev/next - Redirects:
redirects: { '/old': '/new' }inastro.config.mjs - Cookies (SSR):
Astro.cookies.get('name')?.value/.set('name', value, options)
References
Deep-dive docs with full code examples live in references/:
actions.md client-directives.md components.md configuration.md content-collections.md environment-variables.md i18n-routing.md images.md middleware.md routing.md server-islands.md sessions.md ssr-adapters.md styling.md view-transitions.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

