--- 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](https://astro.build/blog/astro-6/)); 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](https://docs.astro.build/en/guides/upgrade-to/v6/): - **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. | Need | Use | Why | | ------------------------------------------------------ | ---------------------------------------- | ---------------------------------------------------------- | | Pure content, no interactivity | `.astro` component, static | Renders to HTML at build, ships **0 KB** JS | | One small interactive widget | UI-framework component + `client:*` | Hydrate just that island; the rest stays static | | Per-request personalization on a mostly-static page | server island (`server:defer`) | Static CDN page + one deferred fragment, no full SSR | | Whole route needs request data on every load | `export const prerender = false` + adapter | Opt that one route into on-demand rendering | | Many static routes generated from data | `getStaticPaths()` | 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. ```astro --- // 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 ---

Hello {user.name}

``` ```astro --- // 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; ---

{post.data.title}

``` 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`. | Directive | Hydrates when | Use for | | ----------------------- | ----------------------------------- | ---------------------------------------------------- | | `client:load` | Immediately on page load | Above-the-fold, must-be-interactive-now controls | | `client:idle` | On `requestIdleCallback` | Important but not first-paint-critical widgets | | `client:visible` | When it scrolls into view (IO) | Below-the-fold carousels, comment boxes, maps | | `client:media={query}` | When a media query matches | Mobile-only menu, desktop-only panel | | `client:only="react"` | Client-only, **no SSR HTML** | Components that crash during SSR (browser-only deps) | ```astro --- import Carousel from "../components/Carousel.tsx"; --- ``` `client:only` gotcha: it **skips SSR entirely**, so the component produces no server HTML (expect a flash/layout shift) and you **must** name the framework (`client:only="react"`) — Astro can't infer it without the server render. Reach for it only when SSR genuinely breaks; otherwise prefer `client:visible`. ## Content collections (Content Layer) Type-safe content lives in a single config file. The path is load-bearing: ```typescript // src/content.config.ts ← v6 path. NOT src/content/config.ts (legacy path removed in v6) import { defineCollection } from "astro:content"; import { z } from "astro/zod"; // v6: z moved OUT of astro:content into astro/zod (Zod 4) import { glob } from "astro/loaders"; const blog = defineCollection({ // glob() sources files from anywhere; `id` comes from the filename minus extension loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/data/blog" }), schema: z.object({ title: z.string(), pubDate: z.coerce.date(), draft: z.boolean().default(false), tags: z.array(z.string()).default([]), }), }); export const collections = { blog }; ``` Query and render in a page. `render()` is now a standalone call (not `entry.render()`): ```astro --- // src/pages/blog/[slug].astro import { getCollection, getEntry, render } from "astro:content"; export async function getStaticPaths() { const posts = await getCollection("blog", ({ data }) => !data.draft); return posts.map((post) => ({ params: { slug: post.id }, props: { post } })); } const { post } = Astro.props; const { Content } = await render(post); ---

{post.data.title}

``` Built-in loaders are `glob()` (many files) and `file()` (one JSON/YAML array). Custom and CMS loaders, Zod 4 schema patterns, collection references, Live Content Collections (real-time data with no rebuild, stable in v6), querying and MDX details → `references/content-layer.md`. ## Server islands When most of a page is static and CDN-cacheable but **one fragment** is per-visitor, use a server island instead of turning the whole route into SSR. The page ships static; the island is fetched and rendered after first paint. ```astro --- // src/components/UserGreeting.astro — rendered on demand, deferred after the static shell const user = await getUserFromCookie(Astro.request); --- Welcome back, {user.name} ``` ```astro --- import UserGreeting from "../components/UserGreeting.astro"; ---

Welcome

``` This beats full SSR when: the page is otherwise cacheable on a CDN, and only a small slice depends on the request. You keep static LCP and personalize without making every request hit the origin. ## Integrations & setup Use `astro add` so it patches `astro.config.mjs` and installs peers in one step: ```bash npx astro add react mdx sitemap ``` - **Tailwind 4** wires through the official **Vite plugin** (`@tailwindcss/vite`), not the legacy `@astrojs/tailwind` integration (that path was for Tailwind 3). - **Fonts API** (stable in v6) self-hosts and optimizes fonts from `astro.config.mjs` — no manual `@font-face`. - **CSP API** (stable in v6) emits a Content-Security-Policy with hashes for your inline scripts/styles. Adapter recipes per platform, hybrid rendering, env handling, SSR endpoints (`src/pages/api/*.ts`) and the Fonts/CSP config → `references/deploy-and-integrations.md`. ## Performance rules - Images: always ``/`