astro-framework

Astro framework specialist for building fast, content-driven websites with islands architecture. Use when creating Astro components, configuring hydration (client:load/idle/visible/media), using server:defer (server islands), Content Layer API (glob/file loaders, live loaders), sessions, astro:env, i18n routing, actions, SSR adapters, view transitions, or integrating React/Vue/Svelte/Solid. Not for full-SPA frameworks (Next.js, Remix, SvelteKit).

36stars2forksUpdated 7/16/2026

#frontend #islands-architecture #ssr #view-transitions #content-collections #astro

Security Assessment

Medium Risk(50/100)

Detected risks:

Secret Exposure([references/actions.md] token =, [references/ssr-adapters.md] token =, [rules/astro-ssr.rule.md] token =)

Sensitive File Access([references/configuration.md] .env, [references/ssr-adapters.md] .env, [references/environment-variables.md] .env)

Security Score50/100

About astro-framework

astro-framework is a specialist skill for building fast, content-driven websites with the Astro framework and its islands architecture. It provides senior-level expertise in selective hydration, content collections, and hybrid rendering, helping decide when to ship JavaScript and when to keep pages static. It activates for tasks like creating Astro components, configuring hydration, using server islands, building content collections with the Content Layer API, setting up SSR adapters, implementing view transitions, managing sessions, configuring type-safe environment variables, i18n routing, actions, and integrating React/Vue/Svelte/Solid — and it explicitly excludes full-SPA frameworks like Next.js, Remix, and SvelteKit.

The skill defines a core workflow (analyze requirements, design structure, implement components, configure routing, optimize delivery) and several expert decision frameworks. It guides output-mode selection between static, hybrid (recommended for ~80% of projects), and server, with concrete signals for when a choice is wrong (e.g. builds over 10 minutes with getStaticPaths suggest switching to hybrid). It details hydration strategy pitfalls for client:load, client:visible, client:idle, and client:media, and a decision tree for server islands (server:defer for per-request data like cart counts or personalization) versus client islands (client:* for interactivity) versus static HTML (no directive, ~90% of most sites). It covers content-collection loader selection — glob() for local markdown/MDX, file() for a single JSON/YAML file, custom async loaders for build-time remote data, and Live Loaders (Astro 6+) for per-request fresh data — with a performance tip to use glob() with retainBody: false for sites over 1000 entries.

It targets frontend engineers building blogs, docs, marketing sites, and hybrid apps such as e-commerce (static catalog plus server:defer price/stock plus client:load add-to-cart). A large set of reference files supports specific tasks — components, client directives, content collections, routing, SSR and adapters, server islands, sessions, view transitions, actions, middleware, styling, images, configuration, and environment variables — loaded as needed. The skill also states when not to use Astro: full SPAs with client-side routing and heavy state, real-time collaborative apps, all-pages-behind-auth sites, or apps needing React Server Components.

FAQ

When should I choose static, hybrid, or server output mode?

Use static for content that changes per-deploy (blogs, docs, landing pages), hybrid for mostly-static sites with some dynamic routes (about 80% of real projects), and server only when over 80% of pages need request data. Warning signs include builds over 10 minutes (switch to hybrid) or prerender=false on most pages (switch to server).

How do I decide between server islands, client islands, and static HTML?

If a component needs server data on each request (cookies, session, DB, personalization) use server:defer. If it needs browser interactivity use a client:* directive. If it needs neither, use no directive so it renders as static HTML with zero JS — which should be about 90% of most sites.

Which content-collection loader should I use?

Use glob() for local markdown/MDX files, file() for a single JSON/YAML data file, a custom async loader for remote API/CMS data at build time, and a Live Loader (Astro 6+) for remote data that must be fresh per request.

When should I not use Astro?

Avoid it for full SPAs with client-side routing and heavy state (Next.js, SvelteKit, Remix), core real-time collaborative features, sites where every page is behind auth with no public content, or when you need React Server Components.

What is a common hydration mistake to avoid?

Using client:visible on a hero or header is wasteful because it is already in the viewport at load and hydrates immediately anyway — use client:load instead. Similarly, client:idle on low-RAM mobile can delay interactivity by 10+ seconds.

All Files

26 files

AGENTS.md5.6 KB