Astro

For content-driven sites (marketing, docs, blogs, libraries). At the verification date the latest release on npm was Astro 7.4.1; check the Astro docs and upgrade guide before starting.

Rules

Rendering

• Default to output: 'static'; pre-render every page that can be pre-rendered.
• Add on-demand rendering only for routes that need request-time data, through the host’s adapter, and record it in an ADR.
• Set site to the production URL and choose trailingSlash ('always' recommended) so canonicals and sitemaps are correct.

Islands

• Ship zero JavaScript by default. Hydrate only interactive components, with the laziest directive that works: client:visible for below-the-fold widgets, client:idle for non-urgent ones, client:load only when needed immediately.
• Prefer vanilla TS or a small framework (Preact, Svelte, Solid) for islands; avoid a heavy framework for one widget.
• Text content is rendered by .astro components, never injected by an island.

Content

• All structured content in content collections with Zod schemas in src/content.config.ts (verify the current file name and loader API for your Astro version).
• Use reference() for relationships so the build fails on unknown slugs.
• Use controlled enums for categories and statuses.
• Only published entries are routed in production builds; drafts are visible locally.
• Derive related lists, tag pages and hubs in one lib/taxonomy.ts, not in each page.

Assets

• Images through astro:assets (<Image>, <Picture>) with explicit dimensions and modern formats.
• Self-host fonts; use Astro’s font tooling if available in your version, otherwise @font-face with woff2 and font-display: swap.

Navigation

• View transitions (<ClientRouter />) are optional. If used: analytics page views fire on astro:page-load, and scripts are written to run on each navigation.

Security

• Use Astro’s built-in CSP support where available (verify for your version) so inline scripts get hashes instead of 'unsafe-inline'.

Quality

• astro check in CI.
• Sitemap via @astrojs/sitemap (Starlight includes it). Exclude noindex pages.

Typical layout

src/
  content.config.ts
  content/<collection>/…
  components/<feature>/…  components/ui/…
  layouts/
  lib/        (seo.ts, schema.ts, taxonomy.ts)
  pages/
  styles/     (tokens.css, base.css)
public/       (_headers, _redirects, robots.txt, favicons)
scripts/      (check-content.ts, check-links.ts)
tests/        (unit/, e2e/)

Checklist

• site, trailingSlash, static output set
• Islands only where interactive, lazily hydrated
• Collections with schemas and references
• Images via astro:assets with dimensions
• astro check in CI