---
id: frontend-astro-patterns
title: Astro — Islands / Static-first / Multi-framework
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [frontend, astro, ssg, vibe-coding]
tech_stack: { language: "TS / Astro", applicable_to: ["Frontend"] }
applied_in: []
aliases: [Astro, islands architecture, static-first, content-driven, multi-framework]
---

# Astro

> Static-first + 작은 JS. **Islands architecture**. React / Vue / Svelte / Solid 동시 사용 가능. Content-heavy site (blog, marketing) 의 sweet spot.

## 📖 핵심 개념
- Static (default): 0 JS shipped.
- Island: 인터랙션 component 만 hydrate.
- Multi-framework: React + Vue + Svelte 한 site.
- Content collection: type-safe MDX.

## 💻 코드 패턴

### 시작
```bash
npm create astro@latest
```

### 기본 page
```astro
---
// Server-side (build time 또는 SSR)
const users = await fetch('https://api.example.com/users').then(r => r.json());
---

<html>
  <head>
    <title>Users</title>
  </head>
  <body>
    <h1>Users</h1>
    <ul>
      {users.map(u => <li>{u.email}</li>)}
    </ul>
  </body>
</html>
```

→ Static HTML 가 generate. 0 JS.

### Island (인터랙션)
```astro
---
import { Counter } from '../components/Counter.tsx';
---

<div>
  <h1>Static heading</h1>
  <Counter client:load />  <!-- island — JS shipped -->
  <p>More static</p>
</div>
```

```tsx
// components/Counter.tsx (React)
import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}
```

### client:* directives
```astro
<Component client:load />        <!-- 즉시 hydrate -->
<Component client:idle />        <!-- requestIdleCallback -->
<Component client:visible />     <!-- IntersectionObserver -->
<Component client:media="(min-width: 768px)" />  <!-- 조건부 -->
<Component client:only="react" />  <!-- SSR 안 — client only -->
```

→ 작은 island 만 JS load.

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

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

→ 같은 page 안 다른 framework. Migration 또는 team별.

### Content collections (type-safe MDX)
```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()),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };
```

```mdx
---
title: My First Post
date: 2026-05-09
tags: [intro]
---

# Hello World

This is my first **blog post**.

import Counter from '../components/Counter.tsx';

<Counter client:load />
```

```astro
---
import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ data }) => !data.draft);
posts.sort((a, b) => b.data.date.getTime() - a.data.date.getTime());
---

<ul>
  {posts.map(post => (
    <li><a href={`/blog/${post.slug}`}>{post.data.title}</a></li>
  ))}
</ul>
```

→ Type-safe content + frontmatter.

### Dynamic route
```astro
---
// src/pages/blog/[slug].astro
import { getCollection, getEntry } 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>
```

→ Static generation 모든 post.

### SSR mode
```ts
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',  // 또는 'hybrid'
  adapter: vercel(),
});
```

→ Static (default) 또는 SSR per route.

### API routes
```ts
// src/pages/api/users.ts
import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ request }) => {
  const users = await db.user.findMany();
  return new Response(JSON.stringify(users), {
    headers: { 'Content-Type': 'application/json' },
  });
};

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();
  // ...
};
```

### View Transitions (built-in)
```astro
---
import { ViewTransitions } from 'astro:transitions';
---

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

```astro
<!-- 자동 page transition -->
<a href="/about">About</a>

<!-- Shared element -->
<img transition:name="hero" src="..." />
```

### Image optimization
```astro
---
import { Image } from 'astro:assets';
import heroImg from '../assets/hero.jpg';
---

<Image src={heroImg} alt="Hero" width={1200} height={600} format="avif" />
```

→ Build 시 다양 size + format 자동 generate.

### Tailwind / styling
```bash
npx astro add tailwind
```

```astro
<div class="grid gap-4 md:grid-cols-3">
  <article class="rounded border p-4">...</article>
</div>
```

### Markdown / MDX rendering
```mdx
---
title: ...
---

# Heading

import Chart from '../components/Chart.tsx';

<Chart client:visible data={[1, 2, 3]} />

Code:

```ts
function hello() { return 'world'; }
```
```

→ Content + interactive component.

### Pagination
```ts
// src/pages/blog/[page].astro
export async function getStaticPaths({ paginate }) {
  const posts = await getCollection('blog');
  return paginate(posts, { pageSize: 10 });
}

const { page } = Astro.props;
```

```astro
<ul>
  {page.data.map(post => <li>...</li>)}
</ul>

{page.url.prev && <a href={page.url.prev}>Prev</a>}
{page.url.next && <a href={page.url.next}>Next</a>}
```

### RSS feed
```ts
// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'My Blog',
    description: '...',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}`,
    })),
  });
}
```

### Performance
```
Static page (no island): 0 JS.
Marketing site: 95+ Lighthouse.
Blog: 100/100 가능.

→ 작은 JS = 빠른 load.
```

### vs Next.js
```
Astro:
+ Static-first
+ 0 JS default
+ Multi-framework
+ Content-driven
- Less interactive (heavy SPA 어려움)

Next:
+ App Router (RSC)
+ 큰 ecosystem
+ Vercel optimization
- More JS (SPA-friendly)
- Single framework (React)
```

→ Marketing / blog / docs = Astro.
   App = Next.

### vs SvelteKit / Nuxt
```
Astro: framework-agnostic, content-first.
SvelteKit: Svelte SPA + SSR.
Nuxt: Vue + meta-framework.
```

### Use cases
```
✅ Blog / personal site
✅ Marketing site
✅ Documentation
✅ Landing page
✅ E-commerce (catalog)
✅ Portfolio

⚠️ Heavy interactive app (SPA 가 낫음)
```

### Deploy
```
- Vercel / Netlify (Static + SSR)
- Cloudflare Pages
- GitHub Pages (static only)
- 자체 server (Node)
```

### CMS 통합
```
- Sanity / Contentful / Strapi
- Markdoc
- Decap CMS (git-based)
- Astro DB (built-in)
```

```ts
// Sanity
import { sanityClient } from 'sanity:client';

const posts = await sanityClient.fetch(`*[_type == "post"]`);
```

### Astro DB
```ts
// db/config.ts
import { defineDb, defineTable, column } from 'astro:db';

const Comment = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    body: column.text(),
    postSlug: column.text(),
    createdAt: column.date({ default: NOW }),
  },
});

export default defineDb({ tables: { Comment } });
```

→ libSQL 기반. 빠른 시작.

### i18n
```ts
// astro.config.mjs
i18n: {
  defaultLocale: 'en',
  locales: ['en', 'ko', 'ja'],
  routing: { prefixDefaultLocale: false },
},
```

```
src/pages/
├── index.astro
├── ko/index.astro
└── ja/index.astro
```

### Streaming SSR
```
Astro 4+ 가 streaming.
Suspense-like — 일부 부분 점진 send.
```

### Test
```bash
yarn add -D vitest @vitest/ui
yarn vitest
```

```ts
import { describe, it, expect } from 'vitest';
import { experimental_AstroContainer } from 'astro/container';
import Card from './Card.astro';

it('renders title', async () => {
  const container = await experimental_AstroContainer.create();
  const result = await container.renderToString(Card, { props: { title: 'Hello' } });
  expect(result).toContain('Hello');
});
```

## 🤔 의사결정 기준
| 상황 | 추천 |
|---|---|
| Blog / docs / marketing | Astro |
| Content-first | Astro + content collection |
| 일부 interactive | Astro + island |
| Heavy SPA | Next / Tanstack Start |
| Multi-framework migration | Astro |
| Static export only | Astro / Hugo / 11ty |

## ❌ 안티패턴
- **모든 게 client:load**: JS bundle 폭발.
- **Big SPA in Astro**: 잘못 선택. Next / Remix.
- **content schema 무**: type 안전 X.
- **Image plain `<img>`**: optimization 없음. Use `<Image>`.
- **Build 매 변경 (큰 site)**: incremental build 필요.
- **SSR 모든 page**: 정적 generation 가 더 빠름.

## 🤖 LLM 활용 힌트
- Static + island = 빠른 site.
- Content collection 으로 type-safe.
- View Transitions built-in.
- Multi-framework 가 migration 친화.

## 🔗 관련 문서
- [[Frontend_Progressive_Enhancement]]
- [[Frontend_View_Transitions_Deep]]
- [[React_Server_Components]]
