사용 시점
- 랜딩 페이지 및 마케팅 사이트
- 기업 웹사이트
- 콘텐츠 중심 사이트(블로그, 문서)
- SEO와 성능이 중요한 모든 프로젝트
- 대부분 정적이며 상호작용이 최소인 사이트
- 빠른 초기 로드와 Core Web Vitals가 필요한 사이트
풀 웹 앱에는 적합하지 않음 — 상호작용 애플리케이션(대시보드, CRUD 앱, 실시간 앱)에는 vue-frontend를 사용하세요.
중요 규칙
- 기본적으로 JS 사용 안 함 — Astro는 클라이언트 지시어를 추가하지 않는 한 JavaScript를 제공하지 않습니다.
- 항상 TypeScript 사용 — 다른 모든 Vera Sesiom 프로젝트와 동일하게 엄격 모드입니다.
- 구조화된 콘텐츠에는 콘텐츠 컬렉션 사용 — 블로그 게시물, 문서, 사례 연구.
- 섬 아키텍처 — 상호작용이 필요한 곳에만 Vue/React 컴포넌트를 사용합니다.
- 기본적으로 정적 출력(SSG) — 동적 콘텐츠가 필요한 경우에만 SSR을 사용합니다.
- 스타일링에는 Tailwind CSS 사용 — Vue 프론트엔드와 동일합니다.
- Screaming Architecture — 폴더는 프레임워크가 아닌 도메인을 나타냅니다.
결정 기준: Astro vs Vue
| Astro를 사용해야 할 때 | Vue를 사용해야 할 때 |
|---|---|
| 랜딩 페이지, 마케팅 사이트 | 웹 애플리케이션(대시보드, 관리자) |
| 콘텐츠 중심(블로그, 문서) | 상호작용이 많은 UI |
| SEO가 중요한 경우 | 실시간 기능이 필요한 경우 |
| 대부분 정적 콘텐츠 | 복잡한 상태 관리 |
| 최소한의 상호작용(양식, 캐러셀) | 전체 SPA 탐색 |
| Zero JS가 기능인 경우 | Vue 생태계 이점이 중요한 경우 |
규칙: 사이트가 사람들이 읽는 콘텐츠라면 → Astro. 사람들이 사용하는 앱이라면 → Vue.
프로젝트 구조 (Screaming Architecture)
apps/landing/ (또는 apps/website/)
├── src/
│ ├── pages/ # 파일 기반 라우팅 (.astro 파일)
│ │ ├── index.astro # 홈페이지
│ │ ├── about.astro # 소개 페이지
│ │ ├── pricing.astro # 가격 페이지
│ │ ├── blog/
│ │ │ ├── index.astro # 블로그 목록
│ │ │ └── [slug].astro # 블로그 게시물 (동적)
│ │ └── contact.astro
│ ├── layouts/ # 페이지 레이아웃
│ │ ├── BaseLayout.astro # 기본 HTML 구조
│ │ ├── BlogLayout.astro # 블로그 게시물 레이아웃
│ │ └── LandingLayout.astro # 랜딩 페이지 레이아웃
│ ├── components/ # Astro 컴포넌트 (기본적으로 정적)
│ │ ├── sections/ # 페이지 섹션
│ │ │ ├── Hero.astro
│ │ │ ├── Features.astro
│ │ │ ├── Pricing.astro
│ │ │ ├── Testimonials.astro
│ │ │ └── CTA.astro
│ │ ├── ui/ # 재사용 가능한 UI 요소
│ │ │ ├── Button.astro
│ │ │ ├── Card.astro
│ │ │ ├── Badge.astro
│ │ │ └── Input.astro
│ │ └── interactive/ # Vue/React 섬
│ │ ├── ContactForm.vue # 유효성 검사가 있는 양식
│ │ ├── Carousel.vue # 이미지 캐러셀
│ │ └── MobileMenu.vue # 모바일 탐색
│ ├── content/ # 콘텐츠 컬렉션
│ │ ├── blog/ # Markdown/MDX 블로그 게시물
│ │ │ ├── post-1.md
│ │ │ └── post-2.mdx
│ │ └── config.ts # 컬렉션 스키마 (Zod)
│ ├── styles/ # 전역 스타일
│ │ └── global.css # Tailwind 불러오기
│ ├── assets/ # 최적화된 이미지, 폰트
│ │ ├── images/
│ │ └── fonts/
│ └── utils/ # 헬퍼 함수
│ ├── date-format.ts
│ └── seo.ts
├── public/ # 정적 자산 (처리 없음)
│ ├── favicon.ico
│ ├── robots.txt
│ └── fonts/
├── astro.config.mjs # Astro 설정
├── tailwind.config.mjs # Tailwind 설정
├── tsconfig.json
└── package.json
Astro 컴포넌트 패턴
모든 .astro 파일은 두 부분(frontmatter(서버 측)와 템플릿(HTML))으로 구성됩니다.
---
// src/components/ui/Button.astro
// Frontmatter: 서버 측에서 실행되며, 브라우저 JS는 없음
export interface Props {
variant?: 'primary' | 'secondary' | 'outline'
size?: 'sm' | 'md' | 'lg'
href?: string
}
const {
variant = 'primary',
size = 'md',
href,
...rest
} = Astro.props
const baseClasses = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors'
const variantClasses = {
primary: 'bg-blue-600 text-white hover:bg-blue-700',
secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50'
}
const sizeClasses = {
sm: 'px-3 py-1.5 text-sm',
md: 'px-4 py-2 text-base',
lg: 'px-6 py-3 text-lg'
}
const classes = `${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`
---
{href ? (
<a href={href} class={classes} {...rest}>
<slot />
</a>
) : (
<button class={classes} {...rest}>
<slot />
</button>
)}
핵심 사항:
- Frontmatter는 빌드 시간(또는 SSR의 경우 요청 시간)에 실행됩니다.
export default가 필요하지 않습니다. 템플릿 자체가 내보내기입니다.- 자식 콘텐츠에는
<slot />을 사용합니다. - Props는 TypeScript 인터페이스로 타입이 지정됩니다.
레이아웃 패턴
---
// src/layouts/BaseLayout.astro
import Nav from '../components/Nav.astro'
import Footer from '../components/Footer.astro'
export interface Props {
title: string
description?: string
image?: string
}
const { title, description = '', image = '/og-default.png' } = Astro.props
const canonicalURL = new URL(Astro.url.pathname, Astro.site)
---
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="canonical" href={canonicalURL} />
<title>{title}</title>
<meta name="description" content={description} />
<!-- OpenGraph -->
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={image} />
<meta property="og:url" href={canonicalURL} />
<meta property="og:type" content="website" />
<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image" />
<slot name="head />
</head>
<body class="bg-white text-gray-900 antialiased">
<Nav />
<main>
<slot />
</main>
<Footer />
</body>
</html>
사용법:
---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import Hero from '../components/sections/Hero.astro'
---
<BaseLayout title="Vera Sesiom - 소프트웨어 개발" description="우리는 의미 있는 소프트웨어를 만듭니다.">
<Hero />
</BaseLayout>
콘텐츠 컬렉션 패턴
Zod 스키마 검증으로 구조화된 콘텐츠를 정의합니다.
// src/content/config.ts
import { defineCollection, z } from 'astro:content'
const blogCollection = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
updatedDate: z.coerce.date().optional(),
author: z.string().default('Vera Sesiom'),
image: z.object({
url: z.string(),
alt: z.string()
}).optional(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false)
})
})
export const collections = {
blog: blogCollection
}
---
title: "랜딩 페이지에 Astro를 선택한 이유"
description: "성능과 개발자 경험이 중요합니다. Astro가 콘텐츠 사이트에 최적인 이유를 소개합니다."
pubDate: 2024-01-15
author: "기술 리드"
image:
url: "/images/blog/astro-landing.jpg"
alt: "현대 웹사이트의 Astro 로고"
tags: ["astro", "performance", "architecture"]
---
내용이 여기에 옵니다...
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content'
import BaseLayout from '../../layouts/BaseLayout.astro'
const posts = (await getCollection('blog'))
.filter(post => !post.data.draft)
.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
---
<BaseLayout title="블로그" description="Vera Sesiom의 최신 기사">
<h1>블로그</h1>
<ul>
{posts.map(post => (
<li>
<a href={`/blog/${post.slug}`}>
<h2>{post.data.title}</h2>
<p>{post.data.description}</p>
<time>{post.data.pubDate.toLocaleDateString()}</time>
</a>
</li>
))}
</ul>
</BaseLayout>
---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content'
import BaseLayout from '../../layouts/BaseLayout.astro'
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()
---
<BaseLayout title={post.data.title} description={post.data.description}>
<article>
<header>
<h1>{post.data.title}</h1>
<time>{post.data.pubDate.toLocaleDateString()}</time>
<p>작성자: {post.data.author}</p>
</header>
<Content />
</article>
</BaseLayout>
섬 아키텍처 (Vue 컴포넌트)
상호작용 컴포넌트는 필요한 경우에만 JS를 제공합니다. 클라이언트 지시어를 사용하여 하이드레이션을 제어하세요.
<!-- src/components/interactive/ContactForm.vue -->
<script setup lang="ts">
import { ref, computed } from 'vue'
const form = ref({
name: '',
email: '',
message: ''
})
const errors = ref<Record<string, string>>({})
const isValid = computed(() => {
return form.value.name &&
form.value.email.includes('@') &&
form.value.message.length > 10
})
async function submitForm() {
if (!isValid.value) return
// API에 제출
const response = await fetch('/api/contact', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(form.value)
})
if (response.ok) {
// 성공 처리
form.value = { name: '', email: '', message: '' }
}
}
</script>
<template>
<form @submit.prevent="submitForm" class="space-y-4">
<div>
<label for="name">이름</label>
<input v-model="form.name" type="text" id="name" required />
</div>
<div>
<label for="email">이메일</label>
<input v-model="form.email" type="email" id="email" required />
</div>
<div>
<label for="message">메시지</label>
<textarea v-model="form.message" id="message" rows="4" required />
</div>
<button type="submit" :disabled="!isValid">
메시지 보내기
</button>
</form>
</template>
Astro에서 사용하기:
---
// src/pages/contact.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import ContactForm from '../components/interactive/ContactForm.vue'
---
<BaseLayout title="문의하기">
<h1>연락 주세요</h1>
<p>여러분의 의견을 듣고 싶습니다.</p>
<!-- client:visible = 스크롤하여 볼 때 하이드레이트 (모범 사례) -->
<ContactForm client:visible />
</BaseLayout>
클라이언트 지시어 결정 트리
| 지시어 | 사용 시점 | JS 제공 시점 |
|---|---|---|
| 지시어 없음 | 정적 콘텐츠, 상호작용 없음 | JS 없음 |
client:visible | 접힌 부분 아래 상호작용(양식, 캐러셀) — 기본값 | 스크롤하여 볼 때 |
client:load | 접힌 부분 위 중요 상호작용 | 즉시 |
client:idle | 중요하지 않은 개선 사항(분석, 채팅) | 페이지가 유휴 상태일 때 |
client:media | 중단점별 조건부(모바일 탐색) | 미디어 쿼리가 일치할 때 |
client:only | SPA와 유사한 컴포넌트(SSR 건너뛰기) | 즉시, SSR 없음 |
모범 사례:
- 기본값은 지시어 없음 — 순수 정적
- 상호작용이 필요할 때 기본값은
client:visible client:load는 드물게 사용 — 접힌 부분 위 중요 항목에만client:idle은 차단하지 않는 개선 사항에 사용
---
<!-- 좋은 예제 -->
import Hero from './Hero.astro' <!-- 정적, JS 없음 -->
import Carousel from './Carousel.vue'
import MobileMenu from './MobileMenu.vue'
import Chat from './Chat.vue'
import Stats from './Stats.astro' <!-- 정적 카운터 = CSS -->
<Hero /> <!-- 정적, 하이드레이션 없음 -->
<Carousel client:visible /> <!-- 볼 때 하이드레이트 -->
<MobileMenu client:media="(max-width: 768px)" /> <!-- 모바일 전용 -->
<Chat client:idle /> <!-- 페이지 안정 후 -->
<Stats /> <!-- 순수 CSS 애니메이션, JS 불필요 -->
이미지 최적화
자동 최적화를 위해 astro:assets를 사용하세요.
---
// src/pages/index.astro
import { Image } from 'astro:assets'
import heroImage from '../assets/images/hero.png'
---
<Image
src={heroImage}
alt="히어로 이미지"
width={800}
height={600}
loading="lazy"
format="webp"
/>
CMS나 외부 소스의 이미지의 경우:
---
import { Image } from 'astro:assets'
---
<Image
src="https://example.com/image.jpg"
alt="외부 이미지"
width={800}
height={600}
/>
규칙:
- CLS 방지를 위해 항상
width와height를 지정하세요. - 접힌 부분 아래 이미지에는
loading="lazy"를 사용하세요. webp또는avif형식을 선호하세요.- 히어로 이미지를 최적화하고 적절한 크기로 유지하세요.
SEO 패턴
---
// src/components/SEO.astro
export interface Props {
title: string
description: string
image?: string
article?: boolean
publishedTime?: Date
author?: string
tags?: string[]
}
const {
title,
description,
image = '/og-default.png',
article = false,
publishedTime,
author,
tags = []
} = Astro.props
const canonicalURL = new URL(Astro.url.pathname, Astro.site)
const imageURL = new URL(image, Astro.site)
---
<!-- 기본 메타 태그 -->
<title>{title}</title>
<meta name="title" content={title} />
<meta name="description" content={description} />
<link rel="canonical" href={canonicalURL} />
<!-- Open Graph -->
<meta property="og:type" content={article ? 'article' : 'website'} />
<meta property="og:url" content={canonicalURL} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={imageURL} />
<!-- Twitter -->
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:url" content={canonicalURL} />
<meta property="twitter:title" content={title} />
<meta property="twitter:description" content={description} />
<meta property="twitter:image" content={imageURL} />
<!-- 조건부 기사 메타 -->
{article && publishedTime && (
<meta property="article:published_time" content={publishedTime.toISOString()} />
)}
{article && author && (
<meta property="article:author" content={author} />
)}
{tags.length > 0 && (
tags.map(tag => <meta property="article:tag" content={tag} />)
)}
<!-- JSON-LD -->
<script type="application/ld+json" set:html={JSON.stringify({
'@context': 'https://schema.org',
'@type': article ? 'Article' : 'WebPage',
'headline': title,
'description': description,
'image': imageURL.toString(),
'url': canonicalURL.toString(),
...(article && publishedTime ? { 'datePublished': publishedTime.toISOString() } : {}),
...(article && author ? { 'author': { '@type': 'Person', 'name': author } } : {})
})} />
Astro 파일에서 Vue 사용
Vue 컴포넌트를 Astro 파일에 직접 가져와서 사용하세요. 모든 상호작용 Vue 컴포넌트에는 client:* 지시어가 필요합니다.
---
// src/pages/features.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import InteractiveDemo from '../components/interactive/InteractiveDemo.vue'
---
<BaseLayout title="기능">
<section>
<h1>우리의 기능</h1>
<InteractiveDemo client:visible />
</section>
</BaseLayout>
Vue 단일 파일 컴포넌트 (SFC) 규칙:
<script setup lang="ts">사용defineProps에 TypeScript 사용- Vue 템플릿에 Tailwind 클래스 사용
- 컴포넌트당 하나의 Vue 파일
배포 설정
// astro.config.mjs
import { defineConfig } from 'astro/config'
import tailwind from '@astrojs/tailwind'
import vue from '@astrojs/vue'
export default defineConfig({
site: 'https://verasesiom.com',
output: 'static', // SSG 기본값
integrations: [
tailwind(),
vue({ appEntrypoint: '/src/vue-app' })
],
image: {
service: { entrypoint: 'astro/assets/services/sharp' }
}
})
환경 변수:
# .env
PUBLIC_SITE_URL=https://verasesiom.com
PUBLIC_API_URL=https://api.verasesiom.com