---
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());
---

<html>
  <body>
    <h1>Posts ({data.length})</h1>
    <Counter client:load />
    <ul>
      {data.map(p => <li>{p.title}</li>)}
    </ul>
  </body>
</html>
```

→ Frontmatter (`---`) = server. Body = HTML + island.

### Hydration directive
```astro
<Counter client:load />        // 즉시
<Counter client:idle />        // requestIdleCallback
<Counter client:visible />     // intersection observer
<Counter client:media='(min-width: 768px)' />
<Counter client:only='react' />  // server render X
```

→ Per-island lazy.

### Multi-framework
```astro
---
import ReactCounter from './ReactCounter.tsx';
import VueCounter from './VueCounter.vue';
import SvelteCounter from './SvelteCounter.svelte';
---

<ReactCounter client:load />
<VueCounter client:visible />
<SvelteCounter client:idle />
```

→ 같은 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 => <a href={`/blog/${p.slug}`}>{p.data.title}</a>)}
```

→ 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';
---

<head>
  <ViewTransitions />
</head>
```

→ 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';
---

<Image src={myImage} alt='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

<Counter client:load />
```

→ Markdown + JSX.

### Slot (component composition)
```astro
---
// Layout.astro
---
<html>
  <body>
    <header><slot name='header' /></header>
    <main><slot /></main>
  </body>
</html>
```

```astro
---
import Layout from '../layouts/Layout.astro';
---
<Layout>
  <h1 slot='header'>Title</h1>
  <p>Content</p>
</Layout>
```

### 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]]
