astro-best-practices

Astro quality patterns: island philosophy, SEO by page type, and Core Web Vitals. Trigger: When reviewing Astro site quality or hydration decisions.

الانتقال إلى التثبيت

المستودع: joabgonzalez/ai-agents-skills
آخر نشاط في المصدر: ٢٧ أبريل ٢٠٢٦ في ١٥:٢١
لغة SKILL.md المكتشفة: الإنجليزية
النجوم: ٧
التفرعات: ٠

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

العودة إلى البحث العودة إلى التثبيت

name	astro-best-practices
description	Astro quality patterns: island philosophy, SEO by page type, and Core Web Vitals. Trigger: When reviewing Astro site quality or hydration decisions.
license	Apache 2.0
metadata	{"version":"1.0","type":"domain"}

Astro Best Practices

Quality patterns for Astro island architecture, SEO strategy, and Core Web Vitals. Complements the astro skill (which covers syntax and directives) — this skill covers architecture decisions.

When to Use

Reviewing an Astro site for quality or hydration decisions
Deciding page-type SEO strategy
Evaluating whether an island is justified
Auditing Core Web Vitals or JS bundle size

Don't use for:

Client directive syntax (use astro)
SEO meta tag implementation details (use web-seo)
Performance tooling and measurement (use web-performance)

Critical Patterns

✅ REQUIRED [CRITICAL]: Zero JS Is the Default

Hydration is a cost, not a feature. Ask "why does this need browser JS?" before every directive.

<!-- ❌ WRONG — client:load as default "just in case" -->
<Nav client:load />
<Footer client:load />
<Sidebar client:load />

<!-- ✅ CORRECT — only hydrate what requires interactivity -->
<SearchBox client:load />
<Nav />
<Footer />

✅ REQUIRED: Hydration Directive Ladder

Choose the least aggressive directive that meets the requirement.

client:load   → above-fold, requires immediate interaction (search, nav toggle)
client:visible → below-fold interactive (comment section, map)
client:idle   → non-critical enhancement (analytics widget, lazy chat)
client:media  → viewport-conditional (mobile-only menu)

<!-- ❌ WRONG — client:load on below-fold, non-critical component -->
<NewsletterForm client:load />

<!-- ✅ CORRECT — defer until visible -->
<NewsletterForm client:visible />

<!-- ✅ Blog post: Article schema + unique description -->
<title>{post.title} | Blog</title>
<meta name="description" content={post.excerpt} />
<meta property="og:type" content="article" />
<script type="application/ld+json">{JSON.stringify(articleSchema)}</script>

<!-- ✅ Paginated list: canonical + rel="next/prev" -->
<link rel="canonical" href={canonicalUrl} />
{page.url.next && <link rel="next" href={page.url.next} />}

// ❌ WRONG — untyped frontmatter, runtime errors on missing fields
const posts = await getCollection('blog');

// ✅ CORRECT — schema validated at build time
const blogSchema = z.object({
  title: z.string(),
  pubDate: z.date(),
  description: z.string().max(160),
  image: z.string().optional(),
});

// ❌ WRONG — SSR on a page that never uses request data
export const prerender = false; // on /about page

// ✅ CORRECT — SSR only for pages that need it
export const prerender = false; // on /dashboard (uses Astro.locals.user)

<!-- ❌ WRONG — 15kb React runtime for a static header -->
<Header client:load />

<!-- ✅ CORRECT — .astro component ships zero JS -->
<Header />

<!-- ✅ LCP: hero image loads immediately with highest priority -->
<img src={hero.src} alt={hero.alt} loading="eager" fetchpriority="high"
     width={hero.width} height={hero.height} />

<!-- ✅ CLS: explicit dimensions on all media prevent layout shift -->
<img src={avatar} alt="User" width="48" height="48" />

Symptom	Cause	Fix
JS bundle > 50kb on static page	client:load on non-interactive component	Remove directive; use .astro
LCP > 2.5s	Hero image missing priority hints	Add `fetchpriority="high"` + `loading="eager"`
CLS on hydration	Island changes size when hydrated	Set explicit width/height on island wrapper
Missing OG image on social share	og:image not in Layout	Add og:image to base Layout component
Build fails on SSR page	Missing adapter	Add SSR adapter in astro.config.mjs
Duplicate content on paginated pages	Missing canonical/rel links	Add canonical + rel="next/prev" per page

Should this component be hydrated?
  → Does it need event listeners or browser APIs?
  → No → Use .astro component (zero JS)
  → Yes → Choose directive from ladder

Which directive?
  → Above-fold, immediate interaction → client:load
  → Below-fold interactive → client:visible
  → Non-critical enhancement → client:idle
  → Viewport-conditional → client:media

SEO for static blog post?
  → Unique title + description + JSON-LD Article schema

SEO for product page?
  → JSON-LD Product schema + canonical on paginated variants

SEO for paginated list?
  → Canonical on each page + rel="next/prev"

Content collection with 5+ entries?
  → Define Zod schema in src/content/config.ts

Page needs user session or request data?
  → SSR (prerender: false) + adapter
  → Otherwise keep as static

Astro vs full SPA decision?
  → Mostly static with islands → Astro
  → Constant mutation + WebSockets + shared client state → SPA framework

---
// src/layouts/BlogPost.astro
const { post } = Astro.props;
const articleSchema = { "@type": "Article", headline: post.title };
---
<html lang="en">
  <head>
    <title>{post.title} | Blog</title>
    <meta name="description" content={post.description} />
    <meta property="og:type" content="article" />
    <script type="application/ld+json" set:html={JSON.stringify(articleSchema)} />
  </head>
  <body>
    <!-- LCP: hero image gets highest fetch priority -->
    <img src={post.hero} alt={post.heroAlt}
         loading="eager" fetchpriority="high"
         width="1200" height="630" />

    <slot />

    <!-- Island justified: requires scroll position + IntersectionObserver -->
    <TableOfContents client:visible headings={post.headings} />
  </body>
</html>