{"slug":"astro-ops","title":"astro-ops","summary":"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.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-30T19:36:40.214311Z","repo":{"url":"https://github.com/0xDarkMatter/claude-mods","stars":43,"forks":7,"license":"MIT","updatedAt":"2026-09-30T15:18:48Z"},"bodyHtml":"
\n

name: astro-ops\ndescription: \"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.\"\nwhen_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'. Covers islands architecture, view transitions, and adapters; not general React/Next.js work.\"\nlicense: MIT\nallowed-tools: \"Read Write Bash\"\nmetadata:\nauthor: claude-mods\nrelated-skills: typescript-ops, tailwind-ops, javascript-ops

\n

Astro Operations

\n
\n

Facts verified as of 2026-07.

\n
\n

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

\n

Rendering Strategy Decision Tree

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

Configuration

\n
// astro.config.mjs\nimport { defineConfig } from 'astro/config';\n\n// SSG (default) - all pages prerendered at build time\nexport default defineConfig({\n  output: 'static',\n});\n\n// SSR - all pages rendered on request\nexport default defineConfig({\n  output: 'server',\n  adapter: cloudflare(), // or vercel(), netlify(), node()\n});\n\n// Hybrid - static default, opt-in SSR per page\nexport default defineConfig({\n  output: 'hybrid',\n  adapter: cloudflare(),\n});\n
\n
---\n// In hybrid mode, opt OUT of prerendering for specific pages:\nexport const prerender = false;\n// In SSR mode, opt IN to prerendering:\nexport const prerender = true;\n---\n
\n

Islands Architecture Quick Reference

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
DirectiveHydrates WhenJS ShippedUse Case
client:loadImmediately on page loadFull bundleAbove-fold interactive (nav, hero CTA)
client:idleAfter page is idle (requestIdleCallback)Full bundleBelow-fold interactive (comment form, chat)
client:visibleWhen scrolled into viewportFull bundleFar-down-page (footer widget, carousel)
client:mediaWhen media query matchesFull bundleMobile-only nav, responsive components
client:only=\"react\"Immediately, skip SSR entirelyFull bundleComponents that can't SSR (canvas, WebGL)
(none)Never - static HTML onlyZero JSStatic content, cards, headers
\n
---\nimport NavBar from '../components/NavBar.tsx';\nimport CommentForm from '../components/CommentForm.tsx';\nimport ImageCarousel from '../components/ImageCarousel.svelte';\nimport MobileMenu from '../components/MobileMenu.vue';\nimport ThreeScene from '../components/ThreeScene.tsx';\n---\n\n<!-- Loads immediately - critical interactivity -->\n<NavBar client:load />\n\n<!-- Loads after page is idle - non-critical -->\n<CommentForm client:idle />\n\n<!-- Loads when scrolled into view - lazy -->\n<ImageCarousel client:visible />\n\n<!-- Loads only on mobile -->\n<MobileMenu client:media=\"(max-width: 768px)\" />\n\n<!-- Client-only, no SSR (WebGL can't run on server) -->\n<ThreeScene client:only=\"react\" />\n
\n

Content Collections Quick Start

\n

Define Schema

\n
// src/content.config.ts (Astro 5) or src/content/config.ts (Astro 4)\nimport { defineCollection, z, reference } from 'astro:content';\nimport { glob } from 'astro/loaders';\n\nconst blog = defineCollection({\n  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),\n  schema: z.object({\n    title: z.string(),\n    description: z.string().max(160),\n    pubDate: z.coerce.date(),\n    updatedDate: z.coerce.date().optional(),\n    heroImage: z.string().optional(),\n    tags: z.array(z.string()).default([]),\n    draft: z.boolean().default(false),\n    author: reference('authors'), // Reference another collection\n  }),\n});\n\nconst authors = defineCollection({\n  loader: glob({ pattern: '**/*.json', base: './src/content/authors' }),\n  schema: z.object({\n    name: z.string(),\n    avatar: z.string(),\n    bio: z.string(),\n    socials: z.object({\n      twitter: z.string().optional(),\n      github: z.string().optional(),\n    }).optional(),\n  }),\n});\n\nexport const collections = { blog, authors };\n
\n

Query Collections

\n
---\nimport { getCollection, getEntry } from 'astro:content';\n\n// Get all non-draft blog posts, sorted by date\nconst posts = (await getCollection('blog', ({ data }) => !data.draft))\n  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());\n\n// Get a single entry\nconst post = await getEntry('blog', 'my-first-post');\n\n// Resolve a reference\nconst author = await getEntry(post.data.author);\n\n// Render content\nconst { Content, headings } = await post.render();\n---\n\n<Content />\n
\n

Content Collections vs External CMS

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CriterionContent CollectionsExternal CMS (Payload, etc.)
Content typeLocal markdown/MDX, docs, blogsRelational data models
AuthorsDevelopers (version-controlled)Editors (admin UI, multi-user auth)
ValidationType-safe via Zod at build timeCMS-side schemas + API contracts
Update cadenceDeploys with the siteIndependent of deployments
API needsNone (build-time queries)REST/GraphQL for other consumers
WorkflowGit PRs, simple reviewEditorial workflows, drafts, roles
\n

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.

\n

Project Structure Reference

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

View Transitions Quick Reference

\n
---\n// src/layouts/BaseLayout.astro\nimport { ViewTransitions } from 'astro:transitions';\n---\n\n<html>\n  <head>\n    <ViewTransitions />\n  </head>\n  <body>\n    <slot />\n  </body>\n</html>\n
\n

Transition Directives

\n
<!-- Persist element across pages (keeps state, avoids re-render) -->\n<audio transition:persist id=\"player\">\n  <source src=\"/music.mp3\" />\n</audio>\n\n<!-- Named transition for animation pairing -->\n<img transition:name=\"hero\" src={post.heroImage} />\n\n<!-- Custom animation -->\n<div transition:animate=\"slide\">Content</div>\n<div transition:animate=\"fade\">Content</div>\n<div transition:animate=\"none\">No animation</div>\n\n<!-- Persist with name (for multiple persistent elements) -->\n<video transition:persist=\"media-player\" />\n
\n

Lifecycle Events

\n
<script>\n  document.addEventListener('astro:before-preparation', (e) => {\n    // Before new page is fetched - cancel navigation, show loading\n  });\n\n  document.addEventListener('astro:after-preparation', (e) => {\n    // New page fetched, before swap\n  });\n\n  document.addEventListener('astro:before-swap', (e) => {\n    // Customize DOM swap behavior\n  });\n\n  document.addEventListener('astro:after-swap', () => {\n    // DOM updated - reinitialize scripts\n  });\n\n  document.addEventListener('astro:page-load', () => {\n    // Page fully loaded (fires on initial + every navigation)\n    // Use this instead of DOMContentLoaded with View Transitions\n  });\n</script>\n
\n

Back/Forward Handling

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

Deployment Decision Tree

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

Adapter Installation

\n
# Cloudflare\nnpx astro add cloudflare\n\n# Vercel\nnpx astro add vercel\n\n# Netlify\nnpx astro add netlify\n\n# Node.js\nnpx astro add node\n
\n

Common Gotchas

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GotchaWhyFix
Hydration mismatch errorsServer 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 clientOnly PUBLIC_ prefixed vars are exposed to client-side codeRename to PUBLIC_MY_VAR or pass via props from server
Dynamic routes 404 in SSGgetStaticPaths() not returning all possible paramsEnsure getStaticPaths() returns every valid path, or switch to hybrid/SSR
Images not optimizingUsing <img> instead of Astro's <Image /> componentImport from astro:assets: import { Image } from 'astro:assets' and use local imports for src
SSR fails without adapteroutput: 'server' or 'hybrid' requires a deployment adapterInstall adapter: npx astro add cloudflare (or vercel, netlify, node)
MDX components not renderingCustom components not passed to MDX contentPass components via <Content components={{ MyComponent }} /> or use astro.config.mjs MDX config
Content collection schema changes not reflectedType generation is cached, stale .astro typesRun astro sync to regenerate types, restart dev server
client:* on Astro componentsClient 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 definedServer-side code cannot access browser globalsGuard with if (typeof window !== 'undefined') or move to client:only
Styles leaking between componentsUsing global CSS instead of scoped stylesUse <style> (scoped by default in .astro) or <style is:global> intentionally
View Transitions break scriptsDOMContentLoaded only fires once with View TransitionsUse astro:page-load event instead, which fires on every navigation
Env vars missing in production.env not loaded or platform env vars not configuredUse envField in astro.config.mjs for validation; set vars in platform dashboard
\n

Production Security Checklist

\n

For every production deployment, address:

\n\n

Reference Files

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FileContentsLines
references/content-collections.mdSchema patterns, Zod types, querying, MDX, content layer API, migrations~500
references/islands-rendering.mdIslands deep dive, client directives, framework integration, server islands~550
references/deployment.mdCloudflare/Vercel/Netlify/Node adapters, env vars, optimization~500
\n

See Also

\n\n","files":[{"path":"assets/.gitkeep","sizeBytes":0,"isText":false},{"path":"references/content-collections.md","sizeBytes":18411,"isText":true},{"path":"references/deployment.md","sizeBytes":21907,"isText":true},{"path":"references/islands-rendering.md","sizeBytes":21094,"isText":true},{"path":"scripts/.gitkeep","sizeBytes":0,"isText":false},{"path":"SKILL.md","sizeBytes":15985,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":7,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-30T19:36:59.734585Z","sha256":"1C5C3A63D0257C3C3B92A5827D0DBEF2ADCAC3F06F37C77F1FBCF157AC22F6B0","sizeBytes":26448},"review":null,"source":{"repositoryUrl":"https://github.com/0xDarkMatter/claude-mods","path":"skills/astro-ops","license":"MIT","commit":"3dfaf0ba5753026a99ee13f9d9ed56b9793bb6e8","subtreeSha":"74178782A6FDDEEF881293F4B4548628F823C9D1C8D88A8EFEF920695ED726F9","lastSyncedAt":"2026-09-30T19:37:28.226022Z"},"reviewedAt":"2026-09-30T19:37:17.98678Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/astro-ops"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart"},{"target":"git","command":"git clone https://github.com/0xDarkMatter/claude-mods.git"}]}