Astro 웹사이트 빌더은(는) 무엇을 하나요?
이 스킬은 테마 선택, 문서 접근, 개발 모범 사례를 안내하여 Astro.build로 웹사이트를 구축하는 데 도움을 줍니다. 사용자가 Astro로 빌드한다고 언급하거나, 웹사이트를 만들고 싶어하거나, Astro 특화 기능에 도움이 필요할 때 이 스킬을 사용하세요.
이 스킬을 사용해야 하는 경우
다음과 같은 경우 이 스킬을 활성화하세요:
- 사용자가 요청에 "Astro" 또는 "astro.build"를 언급할 때
- 사용자가 웹사이트를 구축하려 하고 Astro가 적합할 때 (블로그, 문서, 포트폴리오, 마케팅 사이트 등)
- 사용자가 Astro 프로젝트에 사용할 테마를 선택해야 할 때
- 사용자가 Astro 컴포넌트, 라우팅 또는 설정에 도움이 필요할 때
- 사용자가 React, Vue 또는 다른 프레임워크를 Astro와 통합하려 할 때
- 사용자가 Astro의 문서 또는 모범 사례에 접근해야 할 때
워크플로우 개요
Astro 웹사이트를 구축할 때는 다음 과정을 따르세요:
- 요구사항 파악 - 필요한 웹사이트의 유형과 기능 결정
- 적절한 테마 선택 - 요구사항에 따라 Astro의 무료 테마 중에서 선택
- 문서 참조 - 특정 기능에 대해 Astro 문서 참조
- 프로젝트 초기화 - 프로젝트 구조 설정
- 컴포넌트 개발 - Astro의 컴포넌트 아키텍처를 사용하여 빌드
- 최적화 및 배포 - 성능을 위한 모범 사례 따르기
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 문서가 필요할 때는 다음을 참조하세요:
- 내장 참조:
references/astro_docs.md- 핵심 Astro 개념, 구문 및 일반적인 패턴 포함 - 전체 문서: 포괄적인 정보를 위해
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단계: 컴포넌트 및 페이지 개발
컴포넌트 개발 패턴
src/components/에 컴포넌트 파일 생성- props 인터페이스 정의 (TypeScript 사용 시)
- 컴포넌트 스크립트 작성 (빌드 시 실행)
- 템플릿 생성 (Astro 구문의 HTML)
- 범위 지정 스타일 추가 (선택 사항)
예시:
---
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>
페이지 개발 패턴
src/pages/에 페이지 파일 생성 (라우트 결정)- 필요한 컴포넌트 및 레이아웃 가져오기
- 동적 라우트를 위해 getStaticPaths() 정의
- 컴포넌트를 사용하여 페이지 구성
예시 페이지:
---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';
const title = "My Page";
---
<Layout title={title}>
<Hero />
<!-- 더 많은 콘텐츠 -->
</Layout>
상호작용 추가
클라이언트 측 상호작용이 필요할 때:
- 프레임워크 통합 설치:
npx astro add react - 프레임워크 컴포넌트 생성 (.jsx, .vue, .svelte)
- 가져와서 클라이언트 디렉티브와 함께 사용:
---
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
모범 사례
성능 최적화
- 컴포넌트는 기본적으로 정적 상태 유지 - 정말 필요할 때만
client:*추가 - Astro의 Image 컴포넌트 사용 - 자동 최적화
- 섬 아키텍처 활용 - 기본적으로 최소한의 JavaScript
- 코드 분할 - Astro가 페이지별로 자동 분할
개발 워크플로우
- 구조부터 시작 - 먼저 레이아웃과 기본 페이지 설정
- 컴포넌트 중심 - 재사용 가능한 컴포넌트 구축
- 타입 안전성 - TypeScript를 사용하여 props와 더 나은 개발 경험 제공
- 콘텐츠 컬렉션 - 타입 안전한 콘텐츠 관리
- 로컬에서 테스트 -
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 개발을 위한 주요 참조 자료입니다.
외부 리소스
- Astro 테마: https://astro.build/themes/
- Astro 문서 (LLM 친화적): https://docs.astro.build/llms-full.txt
- Astro 문서: https://docs.astro.build
- Astro Discord: https://astro.build/chat
예제 워크플로우
예제 1: 블로그 구축
사용자: "Astro와 React로 블로그를 만들고 싶어요"
워크플로우:
- 요구사항 식별: 블로그 사이트, React 지원 필요, 무료 테마 선호
- 테마 가져오기:
web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free - 테마 추천: 설명과 함께 블로그 지향 테마 2~3개 제안
references/astro_docs.md를 읽어 컴포넌트 패턴 참조- 설정 안내: 설치 명령어와 구조 제공
- 빌드 도움: 블로그 게시물 레이아웃, 목록 페이지, 개별 게시물 페이지 생성
- 상호작용 추가: 댓글과 같은 기능을 위해
client:load를 사용하여 React 컴포넌트를 추가하는 방법 보여주기
예제 2: 포트폴리오 웹사이트
사용자: "https://astro.build/를 사용하여 저를 위한 포트폴리오 사이트를 만들어주세요"
워크플로우:
- 요구사항 명확히: 무엇을 보여줄까요? (프로젝트, 기술, 경험?)
- Astro 테마 페이지에서 포트폴리오 테마 가져오기
- 사용자 분야(개발자, 디자이너 등)에 따라 최적의 테마 추천
references/astro_docs.md에서 컴포넌트 구문 읽기- 선택한 테마로 프로젝트 구조 설정
- 컴포넌트 생성/커스터마이징 (히어로, 프로젝트 그리드, 소개, 연락처)
- 필요한 경우 부드러운 전환 효과 추가
- Astro의 Image 컴포넌트를 사용하여 이미지 최적화
예제 3: 문서 사이트
사용자: "검색 기능과 다크 모드가 있는 문서 사이트가 필요해요"
워크플로우:
- 식별: 문서 사이트, 검색 및 다크 모드 필요
- Starlight 추천 (공식 Astro 문서 프레임워크)
- 설정 보여주기:
npm create astro@latest -- --template starlight - 전체 Astro 문서에서 Starlight 문서 참조
- 사이드바 내비게이션 구조 설정
- 콘텐츠 구조 설정
- 다크 모드 활성화 (내장)
- 검색 설정 (Pagefind로 내장)
주요 알림
- 컴포넌트 또는 구문 질문에 답변하기 전에 항상
references/astro_docs.md를 먼저 읽으세요 - 사용자가 시작점이 필요할 때 Astro 테마 페이지에서 테마를 가져오세요
- 필요할 때 전체 문서를 위해
web_fetch를 사용하세요 - 간단하게 유지하세요 - Astro는 직관적으로 설계되었습니다. 지나치게 복잡하게 만들지 마세요.
- 섬 아키텍처 - 컴포넌트는 기본적으로 정적입니다.
- 타입 안전성 - 더 나은 개발 경험을 위해 TypeScript 사용을 권장합니다.
성공 기준
Astro 프로젝트가 올바르게 설정되었는지는 다음 기준으로 확인합니다:
- ✅ 프로젝트 구조가 Astro 규칙을 따름
- ✅
src/pages/디렉토리가 존재하고 최소한 index.astro 파일 포함 - ✅ 요구사항에 따라 적절한 테마 선택됨
- ✅ 컴포넌트가 Astro 구문 패턴을 따름
- ✅ 클라이언트 측 상호작용이 필요한 곳에만 추가됨
- ✅ 컴포넌트 props에 대해 TypeScript 인터페이스 정의됨
- ✅ Astro의 Image 컴포넌트를 사용하여 이미지 최적화됨
- ✅
npm run dev로 사이트가 성공적으로 실행됨