跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
营销与销售

astro

Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is `nextjs`).

ericrisco · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add ericrisco/rsc-harness --skill astro

技能说明


name: astro description: "Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is nextjs)." tags: [astro, ssg, islands, content-collections, partial-hydration, marketing-site, frameworks] recommends: [landing-copy, seo-geo, vercel, cloudflare, netlify] origin: risco

Astro 6 — static-first sites, islands, content collections

The prime directive

Ship zero client JavaScript by default. Hydrate the smallest possible surface, as late as you can get away with. An .astro component renders to HTML at build time and ships no runtime; every island is a bundle the visitor downloads, parses, and executes. Content and marketing sites win on TTFB/LCP and Lighthouse, not on React-everywhere. If you find yourself adding client:load to make a page "work," stop — the page already works; you are adding interactivity, and interactivity is the expensive exception, not the default.

First: detect the project version

Astro 6.0 is stable (released 2026-03-10); the Astro 5 line is still production-ready. Do not mix advice across majors — read package.json → the astro version before advising. What v6 changes, per the upgrade-to-v6 guide:

  • Node 22.12.0 or higher is required (18 and 20 are dropped) — check the actual runtime.
  • Content config lives at src/content.config.ts. The legacy src/content/config.ts path is removed, not merely discouraged, and the old auto-detection (legacy.collections) is gone. The legacy.collectionsBackwardsCompat escape hatch is a migration crutch, not a supported layout.
  • Vite 7 and Zod 4 for content schemas — z is imported from astro/zod, not astro:content (see Content collections below).
  • Live Content Collections, the Fonts API and the CSP API are stable.
  • The Rust compiler succeeding the Go one is experimental — do not rely on or configure it in production advice.

Decision table — what kind of thing is this?

Pick the cheapest row that satisfies the requirement. Read top-down; stop at the first match.

NeedUseWhy
Pure content, no interactivity.astro component, staticRenders to HTML at build, ships 0 KB JS
One small interactive widgetUI-framework component + client:*Hydrate just that island; the rest stays static
Per-request personalization on a mostly-static pageserver island (server:defer)Static CDN page + one deferred fragment, no full SSR
Whole route needs request data on every loadexport const prerender = false + adapterOpt that one route into on-demand rendering
Many static routes generated from datagetStaticPaths()Build-time fan-out, still fully static

Rendering model

Default: every page is prerendered to static HTML at build time. You opt into dynamism per route — never the other way around.

---
// src/pages/dashboard.astro — opt this ONE route into on-demand (SSR) rendering.
// Requires a configured adapter (Vercel/Netlify/Cloudflare/Node). Everything else stays static.
export const prerender = false;
const user = await getUser(Astro.request); // runs per request
---
<h1>Hello {user.name}</h1>
---
// src/pages/blog/[slug].astro — many STATIC routes generated from data at build time.
import { getCollection } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
}
const { post } = Astro.props;
---
<h1>{post.data.title}</h1>

In Astro 6 the dev server runs the production runtime (Vite 7 Environment API), so dev no longer diverges from prod on Cloudflare/Bun/Deno — fewer "works in dev, breaks on deploy" surprises. Adapter choice per platform → references/deploy-and-integrations.md.

Islands & client directives

A client:* directive turns a framework component into a hydrated island. Choose the latest directive that still feels instant to the user — never default to client:load.

DirectiveHydrates whenUse for
client:loadImmediately on page loadAbove-the-fold, must-be-interactive-now controls
client:idleOn requestIdleCallbackImportant but not first-paint-critical widgets
client:visibleWhen it scrolls into view (IO)Below-the-fold carousels, comment boxes, maps
client:media={query}When a media query matchesMobile-only menu, desktop-only panel
client:only="react"Client-only, no SSR HTMLComponents that crash during SSR (browser-only deps)
---
import Carousel from "../components/Carousel.tsx";
---
<!-- Bad: a below-the-fold carousel paying for JS at first paint -->
<Carousel client:load />

<!-- Good: defer its bundle until the user actually scrolls to it -->
<Carousel client:visible />

client:only gotcha:

阅读完整来源 ↗