Claude Skill

astro-ops

Astro framework patterns, islands architecture, content collections, rendering strategies, and deployment. Use for: astro, islands architecture, content collections, astro cloudflare, view transitions, partial hydration, astrojs, SSG, SSR, hybrid rendering, astro adapter.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_astro-ops-6aef525.zip · 26 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/astro-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Astro Operations

Facts verified as of 2026-07.

Comprehensive patterns for Astro framework development: islands architecture, content collections, rendering strategies, view transitions, and multi-platform deployment.

Rendering Strategy Decision Tree

Which rendering strategy?
│
├─ Is content mostly static (blog, docs, marketing)?
│  ├─ YES → Does it change less than daily?
│  │  ├─ YES → SSG (output: 'static')
│  │  │        Fastest TTFB, CDN-cacheable, zero runtime cost
│  │  └─ NO  → Hybrid (output: 'hybrid')
│  │           Default static + opt-in SSR per route
│  └─ NO  → Does every page need personalization?
│     ├─ YES → SSR (output: 'server')
│     │        Dynamic per-request, auth-aware, real-time data
│     └─ NO  → Hybrid (output: 'hybrid')
│              Static shell + server islands for dynamic parts
│
├─ Does the app need real-time interactivity (dashboard, SPA)?
│  ├─ YES → Is it a full SPA with client-side routing?
│  │  ├─ YES → Consider React/Vue SPA instead, or Astro + client:only
│  │  └─ NO  → Hybrid + islands architecture
│  │           Interactive islands in static pages
│  └─ NO  → SSG (output: 'static')
│
├─ Build time concerns (>10k pages)?
│  ├─ YES → Hybrid with on-demand rendering
│  │        Prerender popular pages, SSR the long tail
│  └─ NO  → SSG handles it fine
│
└─ Need edge computing (low latency globally)?
   ├─ YES → SSR + Cloudflare/Vercel Edge adapter
   └─ NO  → SSR + Node adapter or SSG

Configuration

// astro.config.mjs
import { defineConfig } from 'astro/config';

// SSG (default) - all pages prerendered at build time
export default defineConfig({
  output: 'static',
});

// SSR - all pages rendered on request
export default defineConfig({
  output: 'server',
  adapter: cloudflare(), // or vercel(), netlify(), node()
});

// Hybrid - static default, opt-in SSR per page
export default defineConfig({
  output: 'hybrid',
  adapter: cloudflare(),
});
---
// In hybrid mode, opt OUT of prerendering for specific pages:
export const prerender = false;
// In SSR mode, opt IN to prerendering:
export const prerender = true;
---

Islands Architecture Quick Reference

Directive Hydrates When JS Shipped Use Case
client:load Immediately on page load Full bundle Above-fold interactive (nav, hero CTA)
client:idle After page is idle (requestIdleCallback) Full bundle Below-fold interactive (comment form, chat)
client:visible When scrolled into viewport Full bundle Far-down-page (footer widget, carousel)
client:media When media query matches Full bundle Mobile-only nav, responsive components
client:only="react" Immediately, skip SSR entirely Full bundle Components that can't SSR (canvas, WebGL)
(none) Never - static HTML only Zero JS Static content, cards, headers
---
import NavBar from '../components/NavBar.tsx';
import CommentForm from '../components/CommentForm.tsx';
import ImageCarousel from '../components/ImageCarousel.svelte';
import MobileMenu from '../components/MobileMenu.vue';
import ThreeScene from '../components/ThreeScene.tsx';
---

<!-- Loads immediately - critical interactivity -->
<NavBar client:load />

<!-- Loads after page is idle - non-critical -->
<CommentForm client:idle />

<!-- Loads when scrolled into view - lazy -->
<ImageCarousel client:visible />

<!-- Loads only on mobile -->
<MobileMenu client:media="(max-width: 768px)" />

<!-- Client-only, no SSR (WebGL can't run on server) -->
<ThreeScene client:only="react" />

Content Collections Quick Start

Define Schema

// src/content.config.ts (Astro 5) or src/content/config.ts (Astro 4)
import { defineCollection, z, reference } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string().max(160),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    author: reference('authors'), // Reference another collection
  }),
});

const authors = defineCollection({
  loader: glob({ pattern: '**/*.json', base: './src/content/authors' }),
  schema: z.object({
    name: z.string(),
    avatar: z.string(),
    bio: z.string(),
    socials: z.object({
      twitter: z.string().optional(),
      github: z.string().optional(),
    }).optional(),
  }),
});

export const collections = { blog, authors };

Query Collections

---
import { getCollection, getEntry } from 'astro:content';

// Get all non-draft blog posts, sorted by date
const posts = (await getCollection('blog', ({ data }) => !data.draft))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

// Get a single entry
const post = await getEntry('blog', 'my-first-post');

// Resolve a reference
const author = await getEntry(post.data.author);

// Render content
const { Content, headings } = await post.render();
---

<Content />

Content Collections vs External CMS

Criterion Content Collections External CMS (Payload, etc.)
Content type Local markdown/MDX, docs, blogs Relational data models
Authors Developers (version-controlled) Editors (admin UI, multi-user auth)
Validation Type-safe via Zod at build time CMS-side schemas + API contracts
Update cadence Deploys with the site Independent of deployments
API needs None (build-time queries) REST/GraphQL for other consumers
Workflow Git PRs, simple review Editorial workflows, drafts, roles

Rule of thumb: start with Content Collections; reach for a CMS only when non-developers need to publish without a deploy, or when content is genuinely relational.

Project Structure Reference

project-root/
├── astro.config.mjs          # Astro configuration
├── tsconfig.json              # TypeScript config (extends astro/tsconfigs)
├── package.json
├── public/                    # Static assets (copied as-is)
│   ├── favicon.svg
│   ├── robots.txt
│   └── og-image.png
├── src/
│   ├── pages/                 # File-based routing
│   │   ├── index.astro        # → /
│   │   ├── about.astro        # → /about
│   │   ├── blog/
│   │   │   ├── index.astro    # → /blog
│   │   │   └── [slug].astro   # → /blog/:slug (dynamic)
│   │   ├── api/
│   │   │   └── search.ts      # → /api/search (API endpoint)
│   │   └── [...slug].astro    # → catch-all/404
│   ├── layouts/
│   │   ├── BaseLayout.astro   # HTML shell, <head>, global styles
│   │   └── BlogPost.astro     # Blog post layout
│   ├── components/
│   │   ├── Header.astro       # Static Astro component
│   │   ├── Footer.astro
│   │   ├── NavBar.tsx         # React island
│   │   └── Counter.svelte     # Svelte island
│   ├── content/               # Content collections source files
│   │   ├── blog/
│   │   │   ├── post-one.md
│   │   │   └── post-two.mdx
│   │   └── authors/
│   │       └── jane.json
│   ├── content.config.ts      # Collection schemas (Astro 5)
│   ├── middleware.ts           # Request/response middleware
│   ├── styles/
│   │   └── global.css
│   └── lib/                   # Shared utilities
│       ├── utils.ts
│       └── constants.ts
└── .env                       # Environment variables

View Transitions Quick Reference

---
// src/layouts/BaseLayout.astro
import { ViewTransitions } from 'astro:transitions';
---

<html>
  <head>
    <ViewTransitions />
  </head>
  <body>
    <slot />
  </body>
</html>

Transition Directives

<!-- Persist element across pages (keeps state, avoids re-render) -->
<audio transition:persist id="player">
  <source src="/music.mp3" />
</audio>

<!-- Named transition for animation pairing -->
<img transition:name="hero" src={post.heroImage} />

<!-- Custom animation -->
<div transition:animate="slide">Content</div>
<div transition:animate="fade">Content</div>
<div transition:animate="none">No animation</div>

<!-- Persist with name (for multiple persistent elements) -->
<video transition:persist="media-player" />

Lifecycle Events

<script>
  document.addEventListener('astro:before-preparation', (e) => {
    // Before new page is fetched - cancel navigation, show loading
  });

  document.addEventListener('astro:after-preparation', (e) => {
    // New page fetched, before swap
  });

  document.addEventListener('astro:before-swap', (e) => {
    // Customize DOM swap behavior
  });

  document.addEventListener('astro:after-swap', () => {
    // DOM updated - reinitialize scripts
  });

  document.addEventListener('astro:page-load', () => {
    // Page fully loaded (fires on initial + every navigation)
    // Use this instead of DOMContentLoaded with View Transitions
  });
</script>

Back/Forward Handling

// astro.config.mjs
export default defineConfig({
  prefetch: {
    prefetchAll: true,         // Prefetch all links on hover
    defaultStrategy: 'hover',  // 'hover' | 'tap' | 'viewport' | 'load'
  },
});
<!-- Per-link prefetch control -->
<a href="/about" data-astro-prefetch>Prefetch on hover (default)</a>
<a href="/blog" data-astro-prefetch="viewport">Prefetch when visible</a>
<a href="/contact" data-astro-prefetch="load">Prefetch immediately</a>
<a href="/external" data-astro-prefetch="false">No prefetch</a>

Deployment Decision Tree

Where to deploy?
│
├─ Need edge computing + Cloudflare ecosystem (KV, D1, R2)?
│  └─ Cloudflare Pages/Workers
│     Adapter: @astrojs/cloudflare
│     Best for: Global edge, Workers bindings, cost-effective
│
├─ Need serverless + Vercel ecosystem (ISR, analytics)?
│  └─ Vercel
│     Adapter: @astrojs/vercel
│     Best for: Next.js migration, image optimization, ISR
│
├─ Need serverless + Netlify ecosystem (forms, identity)?
│  └─ Netlify
│     Adapter: @astrojs/netlify
│     Best for: JAMstack, built-in forms, split testing
│
├─ Need full server control (Docker, custom runtime)?
│  └─ Node.js (standalone or Express/Fastify)
│     Adapter: @astrojs/node
│     Best for: Self-hosted, WebSocket, long-running processes
│
└─ Pure static site (no SSR needed)?
   └─ Any static host (GitHub Pages, S3, Cloudflare Pages)
      No adapter needed, output: 'static'
      Best for: Blogs, docs, marketing sites

Adapter Installation

# Cloudflare
npx astro add cloudflare

# Vercel
npx astro add vercel

# Netlify
npx astro add netlify

# Node.js
npx astro add node

Common Gotchas

Gotcha Why Fix
Hydration mismatch errors Server HTML differs from client render (dates, random IDs, browser APIs) Use client:only for browser-dependent components, or ensure deterministic rendering
import.meta.env undefined in client Only PUBLIC_ prefixed vars are exposed to client-side code Rename to PUBLIC_MY_VAR or pass via props from server
Dynamic routes 404 in SSG getStaticPaths() not returning all possible params Ensure getStaticPaths() returns every valid path, or switch to hybrid/SSR
Images not optimizing Using <img> instead of Astro's <Image /> component Import from astro:assets: import { Image } from 'astro:assets' and use local imports for src
SSR fails without adapter output: 'server' or 'hybrid' requires a deployment adapter Install adapter: npx astro add cloudflare (or vercel, netlify, node)
MDX components not rendering Custom components not passed to MDX content Pass components via <Content components={{ MyComponent }} /> or use astro.config.mjs MDX config
Content collection schema changes not reflected Type generation is cached, stale .astro types Run astro sync to regenerate types, restart dev server
client:* on Astro components Client directives only work on framework components (React, Vue, Svelte) Astro components are static-only; extract interactive parts to a framework component
document / window is not defined Server-side code cannot access browser globals Guard with if (typeof window !== 'undefined') or move to client:only
Styles leaking between components Using global CSS instead of scoped styles Use <style> (scoped by default in .astro) or <style is:global> intentionally
View Transitions break scripts DOMContentLoaded only fires once with View Transitions Use astro:page-load event instead, which fires on every navigation
Env vars missing in production .env not loaded or platform env vars not configured Use envField in astro.config.mjs for validation; set vars in platform dashboard

Production Security Checklist

For every production deployment, address:

  • CSP headers - configure a restrictive Content-Security-Policy (see middleware patterns in references/deployment.md)
  • Remote image restrictions - enforce explicit image.domains / remotePatterns allow-lists; never derive image URLs from user input (SSRF risk)
  • Host header validation - verify the request host matches expected domains in middleware (SSR/hybrid only)
  • Secrets management - on Cloudflare, use Workers Bindings (wrangler secret put), not env vars baked into code; elsewhere use platform secret stores
  • HTTPS only - ensure all external resources (scripts, images, fonts) load over HTTPS
  • Input validation - sanitize all user input in SSR contexts (query params, form bodies, cookies)

Reference Files

File Contents Lines
references/content-collections.md Schema patterns, Zod types, querying, MDX, content layer API, migrations ~500
references/islands-rendering.md Islands deep dive, client directives, framework integration, server islands ~550
references/deployment.md Cloudflare/Vercel/Netlify/Node adapters, env vars, optimization ~500

See Also

  • typescript-ops - TypeScript patterns used throughout Astro projects
  • tailwind-ops - Tailwind CSS integration with Astro (@astrojs/tailwind)
  • javascript-ops - Core JS patterns for client-side island code
  • docker-ops - Docker patterns for self-hosted Astro (Node adapter)
  • Astro Documentation
  • Astro Integration Guide
Files (claude-mods)
  • assets
    • .gitkeep 0 B · in bundle
  • references
    • content-collections.md 18 KB
      Loading…
    • deployment.md 22 KB
      Loading…
    • islands-rendering.md 20.6 KB
      Loading…
  • scripts
    • .gitkeep 0 B · in bundle
  • SKILL.md 15.5 KB
    ---
    name: astro-ops
    description: "Astro framework patterns, rendering strategies, and deployment. Use for: astro, islands architecture, content collections, astro cloudflare, view transitions, partial hydration, astrojs, SSG, SSR, hybrid rendering, astro adapter."
    when_to_use: "Use when building or deploying an Astro site — e.g. 'which rendering mode: SSG, SSR, or hybrid', 'add a React island with client:load', 'set up content collections', 'deploy Astro to Cloudflare/Vercel'. Not general React/Next.js work."
    license: MIT
    allowed-tools: "Read Write Bash"
    metadata:
      author: claude-mods
      related-skills: typescript-ops, tailwind-ops, javascript-ops
    ---
    
    # Astro Operations
    
    > Facts verified as of 2026-07.
    
    Comprehensive patterns for Astro framework development: islands architecture, content collections, rendering strategies, view transitions, and multi-platform deployment.
    
    ## Rendering Strategy Decision Tree
    
    ```
    Which rendering strategy?
    │
    ├─ Is content mostly static (blog, docs, marketing)?
    │  ├─ YES → Does it change less than daily?
    │  │  ├─ YES → SSG (output: 'static')
    │  │  │        Fastest TTFB, CDN-cacheable, zero runtime cost
    │  │  └─ NO  → Hybrid (output: 'hybrid')
    │  │           Default static + opt-in SSR per route
    │  └─ NO  → Does every page need personalization?
    │     ├─ YES → SSR (output: 'server')
    │     │        Dynamic per-request, auth-aware, real-time data
    │     └─ NO  → Hybrid (output: 'hybrid')
    │              Static shell + server islands for dynamic parts
    │
    ├─ Does the app need real-time interactivity (dashboard, SPA)?
    │  ├─ YES → Is it a full SPA with client-side routing?
    │  │  ├─ YES → Consider React/Vue SPA instead, or Astro + client:only
    │  │  └─ NO  → Hybrid + islands architecture
    │  │           Interactive islands in static pages
    │  └─ NO  → SSG (output: 'static')
    │
    ├─ Build time concerns (>10k pages)?
    │  ├─ YES → Hybrid with on-demand rendering
    │  │        Prerender popular pages, SSR the long tail
    │  └─ NO  → SSG handles it fine
    │
    └─ Need edge computing (low latency globally)?
       ├─ YES → SSR + Cloudflare/Vercel Edge adapter
       └─ NO  → SSR + Node adapter or SSG
    ```
    
    ### Configuration
    
    ```typescript
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    
    // SSG (default) - all pages prerendered at build time
    export default defineConfig({
      output: 'static',
    });
    
    // SSR - all pages rendered on request
    export default defineConfig({
      output: 'server',
      adapter: cloudflare(), // or vercel(), netlify(), node()
    });
    
    // Hybrid - static default, opt-in SSR per page
    export default defineConfig({
      output: 'hybrid',
      adapter: cloudflare(),
    });
    ```
    
    ```astro
    ---
    // In hybrid mode, opt OUT of prerendering for specific pages:
    export const prerender = false;
    // In SSR mode, opt IN to prerendering:
    export const prerender = true;
    ---
    ```
    
    ## Islands Architecture Quick Reference
    
    | Directive | Hydrates When | JS Shipped | Use Case |
    |-----------|--------------|------------|----------|
    | `client:load` | Immediately on page load | Full bundle | Above-fold interactive (nav, hero CTA) |
    | `client:idle` | After page is idle (`requestIdleCallback`) | Full bundle | Below-fold interactive (comment form, chat) |
    | `client:visible` | When scrolled into viewport | Full bundle | Far-down-page (footer widget, carousel) |
    | `client:media` | When media query matches | Full bundle | Mobile-only nav, responsive components |
    | `client:only="react"` | Immediately, skip SSR entirely | Full bundle | Components that can't SSR (canvas, WebGL) |
    | (none) | Never - static HTML only | Zero JS | Static content, cards, headers |
    
    ```astro
    ---
    import NavBar from '../components/NavBar.tsx';
    import CommentForm from '../components/CommentForm.tsx';
    import ImageCarousel from '../components/ImageCarousel.svelte';
    import MobileMenu from '../components/MobileMenu.vue';
    import ThreeScene from '../components/ThreeScene.tsx';
    ---
    
    <!-- Loads immediately - critical interactivity -->
    <NavBar client:load />
    
    <!-- Loads after page is idle - non-critical -->
    <CommentForm client:idle />
    
    <!-- Loads when scrolled into view - lazy -->
    <ImageCarousel client:visible />
    
    <!-- Loads only on mobile -->
    <MobileMenu client:media="(max-width: 768px)" />
    
    <!-- Client-only, no SSR (WebGL can't run on server) -->
    <ThreeScene client:only="react" />
    ```
    
    ## Content Collections Quick Start
    
    ### Define Schema
    
    ```typescript
    // src/content.config.ts (Astro 5) or src/content/config.ts (Astro 4)
    import { defineCollection, z, reference } from 'astro:content';
    import { glob } from 'astro/loaders';
    
    const blog = defineCollection({
      loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
      schema: z.object({
        title: z.string(),
        description: z.string().max(160),
        pubDate: z.coerce.date(),
        updatedDate: z.coerce.date().optional(),
        heroImage: z.string().optional(),
        tags: z.array(z.string()).default([]),
        draft: z.boolean().default(false),
        author: reference('authors'), // Reference another collection
      }),
    });
    
    const authors = defineCollection({
      loader: glob({ pattern: '**/*.json', base: './src/content/authors' }),
      schema: z.object({
        name: z.string(),
        avatar: z.string(),
        bio: z.string(),
        socials: z.object({
          twitter: z.string().optional(),
          github: z.string().optional(),
        }).optional(),
      }),
    });
    
    export const collections = { blog, authors };
    ```
    
    ### Query Collections
    
    ```astro
    ---
    import { getCollection, getEntry } from 'astro:content';
    
    // Get all non-draft blog posts, sorted by date
    const posts = (await getCollection('blog', ({ data }) => !data.draft))
      .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
    
    // Get a single entry
    const post = await getEntry('blog', 'my-first-post');
    
    // Resolve a reference
    const author = await getEntry(post.data.author);
    
    // Render content
    const { Content, headings } = await post.render();
    ---
    
    <Content />
    ```
    
    ### Content Collections vs External CMS
    
    | Criterion | Content Collections | External CMS (Payload, etc.) |
    |-----------|--------------------|-----------------------------|
    | Content type | Local markdown/MDX, docs, blogs | Relational data models |
    | Authors | Developers (version-controlled) | Editors (admin UI, multi-user auth) |
    | Validation | Type-safe via Zod at build time | CMS-side schemas + API contracts |
    | Update cadence | Deploys with the site | Independent of deployments |
    | API needs | None (build-time queries) | REST/GraphQL for other consumers |
    | Workflow | Git PRs, simple review | Editorial workflows, drafts, roles |
    
    Rule of thumb: start with Content Collections; reach for a CMS only when non-developers need to publish without a deploy, or when content is genuinely relational.
    
    ## Project Structure Reference
    
    ```
    project-root/
    ├── astro.config.mjs          # Astro configuration
    ├── tsconfig.json              # TypeScript config (extends astro/tsconfigs)
    ├── package.json
    ├── public/                    # Static assets (copied as-is)
    │   ├── favicon.svg
    │   ├── robots.txt
    │   └── og-image.png
    ├── src/
    │   ├── pages/                 # File-based routing
    │   │   ├── index.astro        # → /
    │   │   ├── about.astro        # → /about
    │   │   ├── blog/
    │   │   │   ├── index.astro    # → /blog
    │   │   │   └── [slug].astro   # → /blog/:slug (dynamic)
    │   │   ├── api/
    │   │   │   └── search.ts      # → /api/search (API endpoint)
    │   │   └── [...slug].astro    # → catch-all/404
    │   ├── layouts/
    │   │   ├── BaseLayout.astro   # HTML shell, <head>, global styles
    │   │   └── BlogPost.astro     # Blog post layout
    │   ├── components/
    │   │   ├── Header.astro       # Static Astro component
    │   │   ├── Footer.astro
    │   │   ├── NavBar.tsx         # React island
    │   │   └── Counter.svelte     # Svelte island
    │   ├── content/               # Content collections source files
    │   │   ├── blog/
    │   │   │   ├── post-one.md
    │   │   │   └── post-two.mdx
    │   │   └── authors/
    │   │       └── jane.json
    │   ├── content.config.ts      # Collection schemas (Astro 5)
    │   ├── middleware.ts           # Request/response middleware
    │   ├── styles/
    │   │   └── global.css
    │   └── lib/                   # Shared utilities
    │       ├── utils.ts
    │       └── constants.ts
    └── .env                       # Environment variables
    ```
    
    ## View Transitions Quick Reference
    
    ```astro
    ---
    // src/layouts/BaseLayout.astro
    import { ViewTransitions } from 'astro:transitions';
    ---
    
    <html>
      <head>
        <ViewTransitions />
      </head>
      <body>
        <slot />
      </body>
    </html>
    ```
    
    ### Transition Directives
    
    ```astro
    <!-- Persist element across pages (keeps state, avoids re-render) -->
    <audio transition:persist id="player">
      <source src="/music.mp3" />
    </audio>
    
    <!-- Named transition for animation pairing -->
    <img transition:name="hero" src={post.heroImage} />
    
    <!-- Custom animation -->
    <div transition:animate="slide">Content</div>
    <div transition:animate="fade">Content</div>
    <div transition:animate="none">No animation</div>
    
    <!-- Persist with name (for multiple persistent elements) -->
    <video transition:persist="media-player" />
    ```
    
    ### Lifecycle Events
    
    ```astro
    <script>
      document.addEventListener('astro:before-preparation', (e) => {
        // Before new page is fetched - cancel navigation, show loading
      });
    
      document.addEventListener('astro:after-preparation', (e) => {
        // New page fetched, before swap
      });
    
      document.addEventListener('astro:before-swap', (e) => {
        // Customize DOM swap behavior
      });
    
      document.addEventListener('astro:after-swap', () => {
        // DOM updated - reinitialize scripts
      });
    
      document.addEventListener('astro:page-load', () => {
        // Page fully loaded (fires on initial + every navigation)
        // Use this instead of DOMContentLoaded with View Transitions
      });
    </script>
    ```
    
    ### Back/Forward Handling
    
    ```typescript
    // astro.config.mjs
    export default defineConfig({
      prefetch: {
        prefetchAll: true,         // Prefetch all links on hover
        defaultStrategy: 'hover',  // 'hover' | 'tap' | 'viewport' | 'load'
      },
    });
    ```
    
    ```astro
    <!-- Per-link prefetch control -->
    <a href="/about" data-astro-prefetch>Prefetch on hover (default)</a>
    <a href="/blog" data-astro-prefetch="viewport">Prefetch when visible</a>
    <a href="/contact" data-astro-prefetch="load">Prefetch immediately</a>
    <a href="/external" data-astro-prefetch="false">No prefetch</a>
    ```
    
    ## Deployment Decision Tree
    
    ```
    Where to deploy?
    │
    ├─ Need edge computing + Cloudflare ecosystem (KV, D1, R2)?
    │  └─ Cloudflare Pages/Workers
    │     Adapter: @astrojs/cloudflare
    │     Best for: Global edge, Workers bindings, cost-effective
    │
    ├─ Need serverless + Vercel ecosystem (ISR, analytics)?
    │  └─ Vercel
    │     Adapter: @astrojs/vercel
    │     Best for: Next.js migration, image optimization, ISR
    │
    ├─ Need serverless + Netlify ecosystem (forms, identity)?
    │  └─ Netlify
    │     Adapter: @astrojs/netlify
    │     Best for: JAMstack, built-in forms, split testing
    │
    ├─ Need full server control (Docker, custom runtime)?
    │  └─ Node.js (standalone or Express/Fastify)
    │     Adapter: @astrojs/node
    │     Best for: Self-hosted, WebSocket, long-running processes
    │
    └─ Pure static site (no SSR needed)?
       └─ Any static host (GitHub Pages, S3, Cloudflare Pages)
          No adapter needed, output: 'static'
          Best for: Blogs, docs, marketing sites
    ```
    
    ### Adapter Installation
    
    ```bash
    # Cloudflare
    npx astro add cloudflare
    
    # Vercel
    npx astro add vercel
    
    # Netlify
    npx astro add netlify
    
    # Node.js
    npx astro add node
    ```
    
    ## Common Gotchas
    
    | Gotcha | Why | Fix |
    |--------|-----|-----|
    | Hydration mismatch errors | Server HTML differs from client render (dates, random IDs, browser APIs) | Use `client:only` for browser-dependent components, or ensure deterministic rendering |
    | `import.meta.env` undefined in client | Only `PUBLIC_` prefixed vars are exposed to client-side code | Rename to `PUBLIC_MY_VAR` or pass via props from server |
    | Dynamic routes 404 in SSG | `getStaticPaths()` not returning all possible params | Ensure `getStaticPaths()` returns every valid path, or switch to hybrid/SSR |
    | Images not optimizing | Using `<img>` instead of Astro's `<Image />` component | Import from `astro:assets`: `import { Image } from 'astro:assets'` and use local imports for src |
    | SSR fails without adapter | `output: 'server'` or `'hybrid'` requires a deployment adapter | Install adapter: `npx astro add cloudflare` (or vercel, netlify, node) |
    | MDX components not rendering | Custom components not passed to MDX content | Pass components via `<Content components={{ MyComponent }} />` or use `astro.config.mjs` MDX config |
    | Content collection schema changes not reflected | Type generation is cached, stale `.astro` types | Run `astro sync` to regenerate types, restart dev server |
    | `client:*` on Astro components | Client directives only work on framework components (React, Vue, Svelte) | Astro components are static-only; extract interactive parts to a framework component |
    | `document` / `window` is not defined | Server-side code cannot access browser globals | Guard with `if (typeof window !== 'undefined')` or move to `client:only` |
    | Styles leaking between components | Using global CSS instead of scoped styles | Use `<style>` (scoped by default in .astro) or `<style is:global>` intentionally |
    | View Transitions break scripts | `DOMContentLoaded` only fires once with View Transitions | Use `astro:page-load` event instead, which fires on every navigation |
    | Env vars missing in production | `.env` not loaded or platform env vars not configured | Use `envField` in astro.config.mjs for validation; set vars in platform dashboard |
    
    ## Production Security Checklist
    
    For every production deployment, address:
    
    - **CSP headers** - configure a restrictive `Content-Security-Policy` (see middleware patterns in `references/deployment.md`)
    - **Remote image restrictions** - enforce explicit `image.domains` / `remotePatterns` allow-lists; never derive image URLs from user input (SSRF risk)
    - **Host header validation** - verify the request host matches expected domains in middleware (SSR/hybrid only)
    - **Secrets management** - on Cloudflare, use Workers Bindings (`wrangler secret put`), not env vars baked into code; elsewhere use platform secret stores
    - **HTTPS only** - ensure all external resources (scripts, images, fonts) load over HTTPS
    - **Input validation** - sanitize all user input in SSR contexts (query params, form bodies, cookies)
    
    ## Reference Files
    
    | File | Contents | Lines |
    |------|----------|-------|
    | `references/content-collections.md` | Schema patterns, Zod types, querying, MDX, content layer API, migrations | ~500 |
    | `references/islands-rendering.md` | Islands deep dive, client directives, framework integration, server islands | ~550 |
    | `references/deployment.md` | Cloudflare/Vercel/Netlify/Node adapters, env vars, optimization | ~500 |
    
    ## See Also
    
    - **typescript-ops** - TypeScript patterns used throughout Astro projects
    - **tailwind-ops** - Tailwind CSS integration with Astro (`@astrojs/tailwind`)
    - **javascript-ops** - Core JS patterns for client-side island code
    - **docker-ops** - Docker patterns for self-hosted Astro (Node adapter)
    - [Astro Documentation](https://docs.astro.build)
    - [Astro Integration Guide](https://docs.astro.build/en/guides/integrations-guide/)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.