--- id: frontend-astro-islands-deep title: Astro Islands β€” partial hydration architecture category: Coding status: draft source_trust_level: B verification_status: conceptual created_at: 2026-05-09 updated_at: 2026-05-09 tags: [frontend, astro, vibe-coding] tech_stack: { language: "TS", applicable_to: ["Frontend"] } applied_in: [] aliases: [Astro, islands, partial hydration, MPA, content-driven, HTML-first] --- # Astro Islands > "HTML-first, JS-on-demand". **Static HTML + interactive island 만 hydrate**. Content site / marketing μΉœν™”. Multi-framework. ## πŸ“– 핡심 κ°œλ… - Default = static HTML. - `client:*` directive κ°€ island. - React / Vue / Svelte / Solid λ™μ‹œ. - MPA 식 navigation. ## πŸ’» μ½”λ“œ νŒ¨ν„΄ ### File-based route ``` src/pages/ β”œβ”€β”€ index.astro β”œβ”€β”€ about.astro └── posts/ └── [slug].astro ``` ### Component ```astro --- // src/pages/index.astro import Counter from '../components/Counter.tsx'; const data = await fetch('/api/posts').then(r => r.json()); ---

Posts ({data.length})

``` β†’ Frontmatter (`---`) = server. Body = HTML + island. ### Hydration directive ```astro // μ¦‰μ‹œ // requestIdleCallback // intersection observer // server render X ``` β†’ Per-island lazy. ### Multi-framework ```astro --- import ReactCounter from './ReactCounter.tsx'; import VueCounter from './VueCounter.vue'; import SvelteCounter from './SvelteCounter.svelte'; --- ``` β†’ 같은 page κ°€ μ—¬λŸ¬ framework. Migration μΉœν™”. ### Content collection ```ts // src/content/config.ts import { defineCollection, z } from 'astro:content'; const blog = defineCollection({ schema: z.object({ title: z.string(), date: z.date(), tags: z.array(z.string()), }), }); export const collections = { blog }; ``` ```astro --- import { getCollection } from 'astro:content'; const posts = await getCollection('blog'); --- {posts.map(p => {p.data.title})} ``` β†’ Markdown / MDX κ°€ type-safe. ### Server endpoint ```ts // src/pages/api/users.ts import type { APIRoute } from 'astro'; export const GET: APIRoute = async () => { const users = await db.users.findMany(); return new Response(JSON.stringify(users)); }; ``` ### View Transitions ```astro --- import { ViewTransitions } from 'astro:transitions'; --- ``` β†’ Page navigation κ°€ smooth. β†’ [[Web_View_Transitions_Cross_Doc]]. ### Static generation (SSG default) ```bash astro build # β†’ dist/ (HTML files). ``` ### SSR (μ˜΅μ…˜) ```ts // astro.config.mjs import vercel from '@astrojs/vercel/serverless'; export default { output: 'server', adapter: vercel(), }; ``` β†’ Per-route prerender option. ### Hybrid ```astro --- export const prerender = true; // page-level --- ``` β†’ 맀 page κ°€ SSG / SSR 선택. ### Image optimization ```astro --- import { Image } from 'astro:assets'; import myImage from '../images/hero.png'; --- Hero ``` β†’ μžλ™ resize / format / lazy. ### Performance ``` - 0 JS by default. - 맀 island κ°€ own bundle. - Streamed HTML. β†’ Lighthouse 100. ``` ### Use case ``` βœ“ Marketing site βœ“ Blog / docs βœ“ E-commerce (Shopify Hydrogen alternative) βœ“ Portfolio βœ“ Landing page βœ— 큰 SPA (Next κ°€ 더 μ’‹μŒ). βœ— Dashboard (interactive heavy). ``` ### vs Next.js ``` Next.js: - React-first. - App Router (RSC). - Vercel μΉœν™”. - 큰 ecosystem. Astro: - Multi-framework. - HTML-first (less JS). - μž‘μ€ bundle. - Content-driven. β†’ 정적 / content = Astro. 큰 app = Next. ``` ### vs Eleventy ``` Eleventy: SSG only, JS island μ—†μŒ. Astro: SSG + island. β†’ Astro κ°€ modern. ``` ### MDX ```mdx --- title: My Post --- import Counter from '../components/Counter'; # My Post ``` β†’ Markdown + JSX. ### Slot (component composition) ```astro --- // Layout.astro ---
``` ```astro --- import Layout from '../layouts/Layout.astro'; ---

Title

Content

 ``` ### Production deploy ``` Vercel, Netlify, Cloudflare Pages. - SSG: free / cheap. - SSR: serverless. β†’ λΉ λ₯Έ, scalable. ``` ### Astro DB ```ts // astro:db import { db, eq, Comment } from 'astro:db'; const comments = await db.select().from(Comment).where(eq(Comment.postId, postId)); ``` β†’ Built-in DB (Astro 5+, Turso 기반). ### Real-world - **Astro docs** (자체). - **Lit docs**. - **Microsoft Bun docs**. - **Cloudflare docs**. - **The Guardian** (일뢀). ### LLM μΉœν™” ``` Markdown / MDX κ°€ native. - AI κ°€ μž‘μ„±ν•œ content κ°€ μ¦‰μ‹œ. - Component κ°€ μžλ™ type-check. ``` ## πŸ€” μ˜μ‚¬κ²°μ • κΈ°μ€€ | 상황 | μΆ”μ²œ | |---|---| | Marketing site | Astro | | Blog / docs | Astro | | 큰 SPA | Next.js | | E-commerce static | Astro | | 큰 dynamic | Next / Remix | | Multi-framework migration | Astro | ## ❌ μ•ˆν‹°νŒ¨ν„΄ - **λͺ¨λ“  κ±° client:load**: JS 폭발. - **Server-only logic κ°€ client**: leak. - **No View Transitions**: jarring nav. - **Big island**: bundle 폭발. - **Mix framework κ°€ μ˜λ„ μ—†μŒ**: bundle 폭발. ## πŸ€– LLM ν™œμš© 힌트 - Astro = HTML-first + island. - Multi-framework + content collection. - View Transitions native. - 정적 / content site 의 default. ## πŸ”— κ΄€λ ¨ λ¬Έμ„œ - [[Frontend_Astro_Patterns]] - [[Frontend_SolidJS_Qwik]] - [[Web_View_Transitions_Cross_Doc]]