Communitygithub.com

Astro 웹사이트 빌더

Astro.build로 웹사이트를 구축하는 포괄적인 스킬입니다. 사용자가 Astro를 사용하여 웹사이트를 만들고, Astro의 무료 테마 컬렉션에서 적절한 테마를 선택해야 하며, Astro 문서에 접근하거나 Astro 컴포넌트 및 페이지를 개발하려 할 때 사용합니다. 이 스킬은 테마 선택, 문서 접근, 프로젝트 설정 및 Astro 특화 개발 패턴을 처리합니다.

Astro 웹사이트 빌더란 무엇인가요?

이 스킬은 AI 에이전트가 Astro.build를 사용하여 웹사이트 구축 과정을 사용자에게 완벽하게 안내할 수 있도록 설계되었습니다. 블로그, 포트폴리오, 문서, 랜딩 페이지 등 다양한 웹사이트 유형에 대해 사용자 요구사항을 파악하고, 공식 테마 페이지에서 무료 React 호환 테마를 가져와 분석한 후 2~3개의 최적화된 옵션을 추천합니다. 이 스킬은 `references/astro_docs.md`에 내장된 Astro 핵심 개념 참조와 `https://docs.astro.build/llms-full.txt`의 전체 문서를 가져올 수 있는 기능을 제공하여 컴포넌트 구문, 라우팅, 스타일링 등 모든 개발 단계에서 정확한 정보를 제공합니다. 또한 Astro의 섬 아키텍처(islands architecture)와 `client:*` 디렉티브를 활용한 상호작용 추가 방법, 성능 최적화 모범 사례, TypeScript 타입 안전성 등 Astro 특화 개발 패턴을 상세히 다룹니다. Claude Code, Cursor, Codex와 같은 플랫폼에서 사용할 수 있으며, 웹 검색 및 파일 참조 기능을 통해 실시간으로 정확한 정보를 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanderBite/relay/tree/HEAD/.claude/skills/astro-builder

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

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

문서

Astro 웹사이트 빌더은(는) 무엇을 하나요?

이 스킬은 테마 선택, 문서 접근, 개발 모범 사례를 안내하여 Astro.build로 웹사이트를 구축하는 데 도움을 줍니다. 사용자가 Astro로 빌드한다고 언급하거나, 웹사이트를 만들고 싶어하거나, Astro 특화 기능에 도움이 필요할 때 이 스킬을 사용하세요.

이 스킬을 사용해야 하는 경우

다음과 같은 경우 이 스킬을 활성화하세요:

  • 사용자가 요청에 "Astro" 또는 "astro.build"를 언급할 때
  • 사용자가 웹사이트를 구축하려 하고 Astro가 적합할 때 (블로그, 문서, 포트폴리오, 마케팅 사이트 등)
  • 사용자가 Astro 프로젝트에 사용할 테마를 선택해야 할 때
  • 사용자가 Astro 컴포넌트, 라우팅 또는 설정에 도움이 필요할 때
  • 사용자가 React, Vue 또는 다른 프레임워크를 Astro와 통합하려 할 때
  • 사용자가 Astro의 문서 또는 모범 사례에 접근해야 할 때

워크플로우 개요

Astro 웹사이트를 구축할 때는 다음 과정을 따르세요:

  1. 요구사항 파악 - 필요한 웹사이트의 유형과 기능 결정
  2. 적절한 테마 선택 - 요구사항에 따라 Astro의 무료 테마 중에서 선택
  3. 문서 참조 - 특정 기능에 대해 Astro 문서 참조
  4. 프로젝트 초기화 - 프로젝트 구조 설정
  5. 컴포넌트 개발 - Astro의 컴포넌트 아키텍처를 사용하여 빌드
  6. 최적화 및 배포 - 성능을 위한 모범 사례 따르기

1단계: 요구사항 파악

먼저 웹사이트 유형과 요구사항을 식별하세요:

웹사이트 유형:

  • 블로그/발행 사이트
  • 포트폴리오/쇼케이스
  • 문서 사이트
  • 마케팅/랜딩 페이지
  • 전자상거래 사이트
  • 회사/비즈니스 사이트
  • 개인 웹사이트

물어봐야 할 주요 질문:

  • 사이트의 주요 목적은 무엇인가요?
  • 어떤 콘텐츠 유형이 있나요? (블로그 게시물, 프로젝트, 제품 등)
  • 상호작용이 필요하나요? (양식, 검색, 동적 콘텐츠)
  • 사용자가 선호하는 프레임워크는 무엇인가요? (React, Vue, Svelte 등)
  • 특정 기능이 필요한가요? (다크 모드, i18n, CMS 통합)

2단계: 적절한 테마 선택

web_fetch를 사용하여 무료 React 호환 테마를 탐색하세요:

URL: https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free

테마 선택 기준:

블로그/발행물:

  • 강력한 타이포그래피가 있는 테마 찾기
  • Markdown/MDX를 지원해야 함
  • 태그/카테고리 기능이 있어야 함
  • RSS 피드 지원
  • 고려 대상: astro-paper, astro-blog-template

포트폴리오:

  • 시각적 프로젝트 쇼케이스
  • 소개/연락처 섹션
  • 부드러운 애니메이션
  • 고려 대상: astro-portfolio, personal-portfolio 테마

문서:

  • Starlight 사용 (공식 Astro 문서 프레임워크)
  • 기능: 검색, 사이드바 내비게이션, 다크 모드, i18n
  • 최적 대상: 기술 문서, API 참조, 가이드

랜딩 페이지:

  • CTA가 있는 히어로 섹션
  • 기능/혜택 섹션
  • 연락처 양식
  • 전환 최적화

전자상거래:

  • 제품 목록 및 필터
  • 장바구니 기능
  • 결제 통합 준비
  • 제품 상세 페이지

실행: 테마 페이지를 가져오고, 사용 가능한 테마를 분석한 후 사용자 요구사항에 가장 잘 맞는 2~3개의 옵션을 추천하세요. 각 테마가 적합한 이유를 설명하세요.

3단계: Astro 문서 접근

특정 Astro 문서가 필요할 때는 다음을 참조하세요:

  1. 내장 참조: references/astro_docs.md - 핵심 Astro 개념, 구문 및 일반적인 패턴 포함
  2. 전체 문서: 포괄적인 정보를 위해 https://docs.astro.build/llms-full.txt에서 가져오기

문서를 참조해야 하는 경우:

  • 컴포넌트 구문 질문 → astro_docs.md 참조
  • 라우팅 및 페이지 → astro_docs.md 참조
  • 스타일링 옵션 → astro_docs.md 참조
  • 고급 기능 → docs.astro.build에서 가져오기
  • 통합 설정 → docs.astro.build에서 가져오기
  • API 세부 정보 → docs.astro.build에서 가져오기

4단계: Astro 프로젝트 초기화

Create Astro CLI 사용

# 새 프로젝트 생성
npm create astro@latest

# 또는 특정 템플릿으로 생성
npm create astro@latest -- --template <theme-github-username>/<theme-repo>

프로젝트 구조 설정

초기화 후 적절한 구조를 확인하세요:

project/
├── src/
│   ├── components/     # 재사용 가능한 컴포넌트
│   ├── layouts/        # 페이지 레이아웃
│   ├── pages/          # 라우트 (필수)
│   │   └── index.astro # 홈페이지
│   ├── content/        # 콘텐츠 컬렉션 (선택 사항)
│   └── assets/         # 최적화된 이미지
├── public/             # 정적 에셋
├── astro.config.mjs    # 설정 파일
├── package.json
└── tsconfig.json

중요: 라우팅이 작동하려면 src/pages/ 디렉토리가 필수입니다.

5단계: 컴포넌트 및 페이지 개발

컴포넌트 개발 패턴

  1. src/components/에 컴포넌트 파일 생성
  2. props 인터페이스 정의 (TypeScript 사용 시)
  3. 컴포넌트 스크립트 작성 (빌드 시 실행)
  4. 템플릿 생성 (Astro 구문의 HTML)
  5. 범위 지정 스타일 추가 (선택 사항)

예시:

---
interface Props {
  title: string;
  description?: string;
}
const { title, description } = Astro.props;
---

<article>
  <h2>{title}</h2>
  {description && <p>{description}</p>}
</article>

<style>
  article {
    padding: 1rem;
    border: 1px solid #ccc;
  }
</style>

페이지 개발 패턴

  1. src/pages/에 페이지 파일 생성 (라우트 결정)
  2. 필요한 컴포넌트 및 레이아웃 가져오기
  3. 동적 라우트를 위해 getStaticPaths() 정의
  4. 컴포넌트를 사용하여 페이지 구성

예시 페이지:

---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';

const title = "My Page";
---

<Layout title={title}>
  <Hero />
  <!-- 더 많은 콘텐츠 -->
</Layout>

상호작용 추가

클라이언트 측 상호작용이 필요할 때:

  1. 프레임워크 통합 설치: npx astro add react
  2. 프레임워크 컴포넌트 생성 (.jsx, .vue, .svelte)
  3. 가져와서 클라이언트 디렉티브와 함께 사용:
---
import ReactComponent from '../components/ReactComponent.jsx';
---

<!-- 정적 (JS 없음) -->
<ReactComponent />

<!-- 인터랙티브 -->
<ReactComponent client:load />
<!-- 옵션: client:idle, client:visible, client:media -->

6단계: 필요에 따라 문서 참조

코드를 작성하기 전에 references/astro_docs.md의 관련 섹션을 읽으세요:

  • 컴포넌트 질문 → "컴포넌트 구문" 섹션 읽기
  • 라우팅 문제 → "라우팅" 섹션 읽기
  • 스타일링 → "스타일링" 섹션 읽기
  • 이미지 → "이미지와 에셋" 섹션 읽기
  • 설정 → "설정" 섹션 읽기

고급 주제의 경우 전체 문서를 가져오세요:

web_fetch: https://docs.astro.build/llms-full.txt

모범 사례

성능 최적화

  1. 컴포넌트는 기본적으로 정적 상태 유지 - 정말 필요할 때만 client:* 추가
  2. Astro의 Image 컴포넌트 사용 - 자동 최적화
  3. 섬 아키텍처 활용 - 기본적으로 최소한의 JavaScript
  4. 코드 분할 - Astro가 페이지별로 자동 분할

개발 워크플로우

  1. 구조부터 시작 - 먼저 레이아웃과 기본 페이지 설정
  2. 컴포넌트 중심 - 재사용 가능한 컴포넌트 구축
  3. 타입 안전성 - TypeScript를 사용하여 props와 더 나은 개발 경험 제공
  4. 콘텐츠 컬렉션 - 타입 안전한 콘텐츠 관리
  5. 로컬에서 테스트 - npm run dev를 자주 실행

따라야 할 일반적인 패턴

  • 일관된 페이지 구조를 위해 레이아웃 사용
  • 메타 태그를 위한 SEO 컴포넌트 생성
  • 적절한 TypeScript 인터페이스 설정
  • 적절한 오류 페이지 구현 (404, 500)
  • 이미지에 적절한 대체 텍스트 추가
  • 시맨틱 HTML 사용

문제 해결

일반적인 문제

"모듈을 찾을 수 없음"

  • 올바른 가져오기 경로 확인
  • 통합이 설치되었는지 확인
  • astro.config.mjs에 올바른 통합 설정이 있는지 확인

"페이지가 렌더링되지 않음"

  • 파일이 src/pages/ 디렉토리에 있는지 확인
  • 프론트매터의 구문 오류 확인
  • 올바른 파일 확장자인지 확인 (.astro, .md, .mdx)

"스타일이 적용되지 않음"

  • 범위 지정 스타일은 컴포넌트의 자체 HTML에만 적용됨
  • 전역 스타일에는 is:global 사용
  • Tailwind를 사용하는 경우 Tailwind 설정 확인

"컴포넌트가 인터랙티브하지 않음"

  • 프레임워크 컴포넌트에 client:* 디렉티브 추가
  • 통합이 설치되었는지 확인 (예: @astrojs/react)
  • 브라우저 콘솔에서 JavaScript 오류 확인

리소스

스크립트

  • scripts/theme_analyzer.py - 공식 테마 페이지에서 Astro 테마를 가져와 분석하는 데 도움을 줍니다. 기술 및 가격 필터를 기반으로 테마 옵션을 프로그래밍 방식으로 탐색하려면 이것을 사용하세요.

참조

  • references/astro_docs.md - 먼저 이것을 읽으세요 핵심 Astro 개념, 컴포넌트 구문, 라우팅, 스타일링 및 일반적인 패턴이 포함되어 있습니다. Astro 개발을 위한 주요 참조 자료입니다.

외부 리소스

예제 워크플로우

예제 1: 블로그 구축

사용자: "Astro와 React로 블로그를 만들고 싶어요"

워크플로우:

  1. 요구사항 식별: 블로그 사이트, React 지원 필요, 무료 테마 선호
  2. 테마 가져오기: web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free
  3. 테마 추천: 설명과 함께 블로그 지향 테마 2~3개 제안
  4. references/astro_docs.md를 읽어 컴포넌트 패턴 참조
  5. 설정 안내: 설치 명령어와 구조 제공
  6. 빌드 도움: 블로그 게시물 레이아웃, 목록 페이지, 개별 게시물 페이지 생성
  7. 상호작용 추가: 댓글과 같은 기능을 위해 client:load를 사용하여 React 컴포넌트를 추가하는 방법 보여주기

예제 2: 포트폴리오 웹사이트

사용자: "https://astro.build/를 사용하여 저를 위한 포트폴리오 사이트를 만들어주세요"

워크플로우:

  1. 요구사항 명확히: 무엇을 보여줄까요? (프로젝트, 기술, 경험?)
  2. Astro 테마 페이지에서 포트폴리오 테마 가져오기
  3. 사용자 분야(개발자, 디자이너 등)에 따라 최적의 테마 추천
  4. references/astro_docs.md에서 컴포넌트 구문 읽기
  5. 선택한 테마로 프로젝트 구조 설정
  6. 컴포넌트 생성/커스터마이징 (히어로, 프로젝트 그리드, 소개, 연락처)
  7. 필요한 경우 부드러운 전환 효과 추가
  8. Astro의 Image 컴포넌트를 사용하여 이미지 최적화

예제 3: 문서 사이트

사용자: "검색 기능과 다크 모드가 있는 문서 사이트가 필요해요"

워크플로우:

  1. 식별: 문서 사이트, 검색 및 다크 모드 필요
  2. Starlight 추천 (공식 Astro 문서 프레임워크)
  3. 설정 보여주기: npm create astro@latest -- --template starlight
  4. 전체 Astro 문서에서 Starlight 문서 참조
  5. 사이드바 내비게이션 구조 설정
  6. 콘텐츠 구조 설정
  7. 다크 모드 활성화 (내장)
  8. 검색 설정 (Pagefind로 내장)

주요 알림

  1. 컴포넌트 또는 구문 질문에 답변하기 전에 항상 references/astro_docs.md를 먼저 읽으세요
  2. 사용자가 시작점이 필요할 때 Astro 테마 페이지에서 테마를 가져오세요
  3. 필요할 때 전체 문서를 위해 web_fetch를 사용하세요
  4. 간단하게 유지하세요 - Astro는 직관적으로 설계되었습니다. 지나치게 복잡하게 만들지 마세요.
  5. 섬 아키텍처 - 컴포넌트는 기본적으로 정적입니다.
  6. 타입 안전성 - 더 나은 개발 경험을 위해 TypeScript 사용을 권장합니다.

성공 기준

Astro 프로젝트가 올바르게 설정되었는지는 다음 기준으로 확인합니다:

  • ✅ 프로젝트 구조가 Astro 규칙을 따름
  • ✅ src/pages/ 디렉토리가 존재하고 최소한 index.astro 파일 포함
  • ✅ 요구사항에 따라 적절한 테마 선택됨
  • ✅ 컴포넌트가 Astro 구문 패턴을 따름
  • ✅ 클라이언트 측 상호작용이 필요한 곳에만 추가됨
  • ✅ 컴포넌트 props에 대해 TypeScript 인터페이스 정의됨
  • ✅ Astro의 Image 컴포넌트를 사용하여 이미지 최적화됨
  • ✅ npm run dev로 사이트가 성공적으로 실행됨

관련 스킬