Communitygithub.com

asolis87/보완-식품-앱

Vera Sesiom의 Astro 기반 랜딩 페이지 및 콘텐츠 사이트, SSG 프로젝트를 위한 규칙과 패턴입니다. 기본적으로 JS를 사용하지 않고, Vue Island로 상호작용을 추가하며, 콘텐츠 우선 아키텍처를 따릅니다.

보완-식품-앱란 무엇인가요?

이 Astro 스킬은 랜딩 페이지, 마케팅 사이트, 블로그, 문서 등 콘텐츠 중심의 정적 사이트를 구축하기 위한 포괄적인 가이드입니다. 기본적으로 JS를 배포하지 않아(Zero JS by default) 성능과 SEO(Core Web Vitals)를 최적화하고, 필요한 부분에만 Vue Island를 사용해 상호작용을 추가하는 섬 아키텍처를 채택합니다. Tailwind CSS로 스타일링하고 TypeScript를 엄격하게 사용하며, Screaming Architecture 원칙에 따라 프로젝트 구조를 구성합니다. 콘텐츠 컬렉션(Content Collections)을 통해 블로그나 문서 같은 구조화된 콘텐츠를 Zod 스키마로 검증하고, `astro:assets`로 이미지를 자동 최적화합니다. 이 스킬은 Vue를 사용하는 풀 웹 앱이 아니라 정적 콘텐츠 사이트에만 적합하며, 콘텐츠를 '읽는' 사이트에는 Astro, '사용하는' 앱에는 Vue라는 명확한 기준을 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/asolis87/complementary-food-app/tree/HEAD/.agents/skills/astro-landing

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

사용 시점

  • 랜딩 페이지 및 마케팅 사이트
  • 기업 웹사이트
  • 콘텐츠 중심 사이트(블로그, 문서)
  • SEO와 성능이 중요한 모든 프로젝트
  • 대부분 정적이며 상호작용이 최소인 사이트
  • 빠른 초기 로드와 Core Web Vitals가 필요한 사이트

풀 웹 앱에는 적합하지 않음 — 상호작용 애플리케이션(대시보드, CRUD 앱, 실시간 앱)에는 vue-frontend를 사용하세요.


중요 규칙

  1. 기본적으로 JS 사용 안 함 — Astro는 클라이언트 지시어를 추가하지 않는 한 JavaScript를 제공하지 않습니다.
  2. 항상 TypeScript 사용 — 다른 모든 Vera Sesiom 프로젝트와 동일하게 엄격 모드입니다.
  3. 구조화된 콘텐츠에는 콘텐츠 컬렉션 사용 — 블로그 게시물, 문서, 사례 연구.
  4. 섬 아키텍처 — 상호작용이 필요한 곳에만 Vue/React 컴포넌트를 사용합니다.
  5. 기본적으로 정적 출력(SSG) — 동적 콘텐츠가 필요한 경우에만 SSR을 사용합니다.
  6. 스타일링에는 Tailwind CSS 사용 — Vue 프론트엔드와 동일합니다.
  7. 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:onlySPA와 유사한 컴포넌트(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

관련 스킬