---

name: astro description: "Practitioner-grade reference knowledge for the Astro framework. Covers component syntax, islands architecture, file-based routing, Content Collections, SSG/SSR modes, integrations (Tailwind, MDX, Sitemap, astro:assets), build pipeline, deployment targets, performance patterns, and security defaults. Activate when authoring or reviewing .astro files or any project with astro in package.json." license: Apache-2.0 compatibility: "Requires Astro >= 4.0 and Node >= 18." metadata: provenance: canonical: "https://github.com/crewrig/crewrig" feedback: "https://github.com/crewrig/crewrig" version: "1.0.2"

Astro

Practitioner reference for building sites and apps with the Astro framework. Activate whenever the change touches a .astro file, an astro.config.mjs, a content collection schema, an Astro integration, or any project that lists astro in its package.json.

Astro's defining trait is the server-first rendering model with opt-in client islands. Treat every page as HTML by default; reach for JavaScript only where the interaction model requires it. The patterns below are organized around that bias.

When to activate

• Authoring or reviewing .astro components, layouts, and pages.
• Wiring Content Collections, dynamic routes, or getStaticPaths.
• Configuring SSG, SSR, or hybrid output and selecting an adapter.
• Installing and tuning integrations (@astrojs/tailwind, @astrojs/mdx, @astrojs/sitemap, astro:assets).
• Editing astro.config.mjs, Vite config, or environment variables.
• Diagnosing build failures, hydration mismatches, or Core Web Vitals regressions inside an Astro project.

1. Component syntax

An .astro file has two parts: a frontmatter fence of server-side TypeScript/JavaScript delimited by ---, and an HTML-like template that follows. The frontmatter runs once at build time (SSG) or per request (SSR); never in the browser.

--- 
// Server-side: runs at build or request time, never in the browser.
import Layout from "../layouts/Base.astro";
import Button from "../components/Button.astro";

interface Props {
  title: string;
  cta?: string;
}

const { title, cta = "Read more" } = Astro.props;
const items = await fetch("https://api.example.com/items").then((r) =>
  r.json(),
);
--- 

<Layout title={title}>
  <h1>{title}</h1>
  <ul>
    {items.map((item) => <li>{item.name}</li>)}
  </ul>

  <Button>{cta}</Button>

  <slot name="footer" />
</Layout>

<style>
  /* Scoped by default — Astro hashes class names. */
  h1 {
    font-size: var(--font-size-xl);
    color: var(--color-accent);
  }
</style>

Key rules:

• Props are typed via a Props interface and read from Astro.props. Defaults live in the destructuring assignment.
• Slots project children. Use <slot /> for the default slot and <slot name="foo" /> for named slots; the parent supplies content with slot="foo".
• Imports in the frontmatter are tree-shaken. Components are rendered server-side unless a client:* directive is attached.
• <style> blocks are scoped to the component by default. Use <style is:global> to opt out, sparingly. Prefer design tokens.
• <script> blocks are bundled, hoisted, and deferred by default. Use is:inline only when you have a clear reason (third-party shims, JSON-LD).

2. Islands architecture

Astro ships zero JavaScript by default. To hydrate a UI framework component (React, Vue, Svelte, Solid, Preact) you attach a client:* directive. Each directive is a different hydration strategy — choose deliberately.

--- 
import Counter from "../components/Counter.jsx";
import HeavyChart from "../components/HeavyChart.svelte";
import CartDrawer from "../components/CartDrawer.vue";
import LiveMap from "../components/LiveMap.tsx";
--- 

<!-- Above the fold, must be interactive immediately. -->
<Counter client:load />

<!-- Non-critical; hydrate when the browser is idle. -->
<CartDrawer client:idle />

<!-- Below the fold; hydrate when it scrolls into view. -->
<HeavyChart client:visible />

<!-- Client-only widget — no SSR (e.g. WebGL, browser-only API). -->
<LiveMap client:only="react" />

| Directive | Use-case | | -------------------- | ------------------------------------------------------------------------ | | client:load | Above-the-fold, interactive immediately (header search, primary CTA). | | client:idle | Low-priority interactivity that can wait (cart drawer, preferences). | | client:visible | Below-the-fold widgets — hydrates via IntersectionObserver. | | client:media | Hydrates only when a media query matches (mobile menu on narrow screens).| | client:only="..." | Skip SSR entirely; render only in the browser. Specify the framework. |

Rule of thumb: client:visible and client:idle are the default. client:load is reserved for genuine above-the-fold interactivity. client:only is an escape hatch for code that cannot run server-side.

3. File-based routing

Every .astro, .md, or .mdx file under src/pages/ becomes a route. The file path is the URL.

src/pages/
├── index.astro              → /
├── about.astro              → /about
├── blog/
│   ├── index.astro          → /blog
│   └── [slug].astro         → /blog/:slug      (dynamic param)
└── docs/
    └── [...path].astro      → /docs/*          (rest param)

For static output, dynamic and rest routes must export getStaticPaths() to enumerate the paths to pre-render:

--- 
import { getCollection } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
--- 

<article>
  <h1>{post.data.title}</h1>
  <Content />
</article>

In SSR mode, dynamic routes are resolved per request and getStaticPaths is not required. Use Astro.params to read params.

4. Content Collections

Content Collections give Markdown/MDX/JSON content type-safe frontmatter via Zod. Define a collection in src/content/config.ts:

import { defineCollection, z } from "astro:content";

const blog = defineCollection({
  type: "content", // "content" for md/mdx, "data" for json/yaml
  schema: z.object({
    title: z.string().max(80),
    description: z.string(),
    pubDate: z.coerce.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { blog };

Read collections from any .astro file with type-safe APIs:

import { getCollection, getEntry } from "astro:content";

// All published posts, newest first.
const posts = (await getCollection("blog", ({ data }) => !data.draft)).sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
);

// A single entry by slug.
const post = await getEntry("blog", "hello-world");

Schema violations fail the build with a precise error pointing to the offending file and field. Treat content collections as the default shape for any structured markdown content.

5. SSG vs SSR

Astro supports three output modes set in astro.config.mjs:

import { defineConfig } from "astro";
import netlify from "@astrojs/netlify";

export default defineConfig({
  // "static"  → pre-render every page at build time (default).
  // "server"  → render every page on demand.
  // "hybrid"  → server by default, opt pages into pre-render.
  output: "hybrid",
  adapter: netlify(),
});

In hybrid mode, individual pages opt into pre-rendering:

--- 
export const prerender = true;
--- 

Adapter selection by deployment target:

| Target | Adapter | | ---------------- | ---------------------- | | Node.js server | @astrojs/node | | Netlify | @astrojs/netlify | | Vercel | @astrojs/vercel | | Cloudflare Pages | @astrojs/cloudflare |

Pick static unless a feature genuinely requires server execution (authenticated routes, dynamic form handling, on-demand image transforms). Pre-rendering is the cheapest, fastest, safest default.

6. Integrations

Integrations are registered in astro.config.mjs and add framework support, build steps, or runtime helpers.

import { defineConfig } from "astro";
import tailwind from "@astrojs/tailwind";
import mdx from "@astrojs/mdx";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://example.com",
  integrations: [tailwind(), mdx(), sitemap()],
});

Common integrations:

• @astrojs/tailwind — wires Tailwind through Vite; the tailwind.config.{js,cjs,mjs} is auto-detected. Set applyBaseStyles: false if you provide your own reset.
• @astrojs/mdx — enables .mdx files with full component imports and JSX inside Markdown.
• @astrojs/sitemap — emits sitemap-index.xml and sitemap-0.xml at build time. Requires the top-level site option.
• astro:assets — built-in (no install). Provides <Image>, <Picture>, and the getImage() helper for build-time image optimization:

--- 
import { Image, Picture } from "astro:assets";
import hero from "../assets/hero.jpg";
--- 

<Image
  src={hero}
  alt="Product hero shot"
  widths={[400, 800, 1200]}
  sizes="(min-width: 768px) 50vw, 100vw"
  loading="eager"
  fetchpriority="high"
/>

<Picture
  src={hero}
  alt="Decorative banner"
  formats={["avif", "webp"]}
  widths={[400, 800, 1200]}
/>

7. Build pipeline

astro.config.mjs is the single source of truth. Extend Vite directly via the vite key when needed.

import { defineConfig, envField } from "astro";

export default defineConfig({
  site: "https://example.com",
  base: "/",
  trailingSlash: "ignore",
  build: {
    format: "directory", // /about/index.html vs /about.html
    assets: "_assets",
  },
  env: {
    schema: {
      PUBLIC_ANALYTICS_ID: envField.string({
        context: "client",
        access: "public",
      }),
      API_TOKEN: envField.string({
        context: "server",
        access: "secret",
      }),
    },
  },
  vite: {
    ssr: { noExternal: ["some-esm-only-pkg"] },
  },
});

Environment variables follow two rules:

• import.meta.env exposes anything declared in .env. Only variables prefixed with PUBLIC_ are inlined into client bundles. Everything else is server-only.
• astro:env (Astro 5+) replaces ad-hoc usage with a typed schema. Mark each variable as context: "client" | "server" and access: "public" | "secret". Misuse fails the build.

// Safe in a client island.
import { PUBLIC_ANALYTICS_ID } from "astro:env/client";

// Safe only in frontmatter or server-only modules.
import { API_TOKEN } from "astro:env/server";

8. Deployment

Each target has a canonical adapter and a typical wiring. Pick the adapter first; the rest of the config follows.

# .github/workflows/deploy-gh-pages.yml — static output + GitHub Pages
name: Deploy
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

• GitHub Pages — use the static output and the workflow above, or the @astrojs/github-pages helper. Set site and base to match the repo URL.
• **Ne