FW Writing Astro
범위 및 최초 결정
이 스킬은 Astro 고유의 컴포넌트, 라우팅, 콘텐츠, 렌더링 및 통합을 위해 사용합니다. React 내부, 백엔드 아키텍처 또는 배포 제공자를 규정하는 데 사용하지 말고, 필요한 경우에만 관련 프레임워크/런타임 스킬을 함께 사용하십시오.
편집하기 전에 package.json, lockfile, Astro 및 어댑터 버전, astro.config.*, tsconfig, 기존 라우트/레이아웃/콘텐츠 구성, 그리고 저장소 스크립트를 검사하십시오. 설치된 버전의 문서와 기존 관례를 따르십시오. 승인 없이 통합 설치, 의존성 업그레이드, 배포 또는 유료 서비스 호출을 수행하지 마십시오.
- 미리 빌드할 수 있는 콘텐츠에는 사전 렌더링된 HTML을 선호하십시오. Frontmatter는 사전 렌더링된 라우트의 경우 빌드 시점에 실행되고, 온디맨드 라우트의 경우 서버에서 실행됩니다. 브라우저 코드가 아닙니다.
- 인증된 콘텐츠나 최신 데이터와 같이 실제 요청 시점이 필요한 경우에 SSR을 사용하십시오. SSR에는 호환 가능한 어댑터가 필요합니다. 현재 모델을 지원하는 버전에서는 기본 정적 출력에서
export const prerender = false로 개별 라우트를 SSR로 전환할 수 있습니다.output: 'server'는 SSR을 기본값으로 만들고prerender = true예외를 허용합니다. 이전 버전은 하이브리드 구성이 다르므로 마이그레이션 전에 검사하십시오. - 완전 정적 사이트는 일반적으로 어댑터가 필요하지 않습니다. Astro를 Cloudflare와 동일시하거나 정적 콘텐츠에 SSR을 강제하지 마십시오.
- 접근성, 이스케이프 및 신뢰 경계를 유지하십시오. 신뢰할 수 없는 HTML을
set:html로 삽입하지 말고, 실제 입력 경계에서 신뢰되는 형식의 렌더링을 살균하십시오.
네이티브 컴포넌트 및 유효한 Props
레이아웃 및 정적 콘텐츠에는 .astro 컴포넌트를 사용하십시오. 컴포넌트가 props를 받으면 Props를 선언하고, props가 없는 페이지에는 의례적인 인터페이스가 필요하지 않습니다. 실제 요소의 속성을 사용하고, 속성을 의도적으로 전달하며, 호환되지 않는 속성 집합을 가진 다형성 태그를 피하십시오. 링크된 카드는 href를 article에 보내는 대신 article 내부의 링크를 사용할 수 있습니다. 래핑 앵커 내부에 대화형 컨트롤을 중첩하지 마십시오.
ASTRO-CARD — 완전한 src/components/Card.astro; CSS 라이브러리 불필요:
---
import type { HTMLAttributes } from 'astro/types';
interface Props extends Omit<HTMLAttributes<'article'>, 'title'> {
title: string;
description?: string;
href?: string;
}
const { title, description, href, class: className, ...rest } = Astro.props;
---
<article {...rest} class:list={['card', className]}>
<h2>{href ? <a href={href}>{title}</a> : title}</h2>
{description && <p>{description}</p>}
<slot />
</article>
명시적인 콘텐츠 영역에는 명명된 슬롯을 사용하고 조건부 클래스에는 class:list를 사용하십시오. 신뢰할 수 없는 링크 대상은 별도로 검증하십시오. 문자열 타입은 URL 검증이 아닙니다.
프레임워크 아일랜드 이전의 작은 브라우저 동작
먼저 시맨틱 HTML(details, 네이티브 폼)을 사용하고, 브라우저 동작이 필요할 때 처리된 작은 <script>를 사용하십시오. 메뉴 토글만을 위해 React/Vue/Svelte를 추가하지 마십시오. Astro 스크립트는 번들링/중복 제거됩니다. 모든 컴포넌트 인스턴스를 선택하거나 범위가 지정된 사용자 정의 요소를 사용하십시오. 클라이언트 측 탐색을 사용하는 경우 설치된 라우터의 라이프사이클을 따르고 중복 리스너를 피하십시오. Frontmatter 값은 브라우저 스크립트에서 자동으로 사용할 수 없습니다. 명시적인 DOM 속성 또는 props를 통해서만 비밀이 아닌 데이터를 전달하십시오.
ASTRO-BUTTON — 완전한 src/components/Counter.astro, 일반적인 전체 페이지 탐색용:
<button type="button" data-counter aria-label="Increment count">0</button>
<script>
document.querySelectorAll<HTMLButtonElement>('button[data-counter]').forEach((button) => {
let count = 0;
button.addEventListener('click', () => {
button.textContent = String(++count);
});
});
</script>
기존 프레임워크 컴포넌트나 상당한 대화형 상태가 정당화되고 이미 설치된 통합이 있는 경우 프레임워크 아일랜드를 사용하십시오. 즉시 필요한 동작에는 client:load, 중요하지 않은 동작에는 client:idle, 화면 밖 콘텐츠에는 client:visible, 실제 미디어 종속 요구사항에는 client:media를 선택하십시오. client:* 지시문이 없는 컴포넌트는 프레임워크 수화 없이 HTML을 렌더링합니다. client:only는 서버 렌더링을 건너뛰며, 맹목적인 해결 방법이 아닌 의도적인 로딩/폴백 경험이 필요합니다.
콘텐츠 컬렉션은 설치된 버전을 따름
모든 개별 페이지가 아닌 반복되는 구조화된 콘텐츠에 컬렉션을 사용하십시오. 편집하기 전에 기존 구성과 항목 식별자를 검사하십시오:
- Astro 5는 일반적으로
src/content.config.ts에 위치하는 콘텐츠 레이어 로더 모델을 도입했습니다. 레거시 프로젝트는 로더 대신src/content/config.ts와type: 'content'를 사용할 수 있습니다. 이들은 상호 교환 가능한 파일 위치/API가 아닙니다. - 설치된 Zod 내보내기를 확인하십시오. 다음 예제는 Astro 5의
astro:content에서z내보내기를 대상으로 합니다. 현재 문서는astro/zod를 사용합니다. 해당 모듈이 없는 버전에서 기계적으로 import를 교체하지 마십시오. - 로더 항목은
id를 사용합니다. 레거시slug또는entry.render()API를 가정하지 마십시오. 콘텐츠 레이어 렌더링의 경우 지원되는render(entry)헬퍼를 사용하십시오. MDX 파일이 포함된 경우 MDX 통합이 필요합니다.
ASTRO-COLLECTION-V5 — Astro 5용 로컬 Markdown 항목이 있는 완전한 src/content.config.ts:
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';
const blog = defineCollection({
loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
updatedDate: z.coerce.date().optional(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = { blog };
ASTRO-COLLECTION-LIST — 완전한 페이지 src/pages/blog/index.astro, 해당 컬렉션 및 하나 이상의 스키마 유효성 Markdown 항목과 쌍을 이룸:
---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog', ({ data }) => !import.meta.env.PROD || !data.draft);
posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<h1>Blog</h1>
<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>
이 목록은 의도적으로 세부 페이지 URL을 만들지 않습니다. 링크를 추가하는 경우 일치하는 동적 라우트와 사전 렌더링된 페이지용 getStaticPaths()를 구현하십시오. 세부 라우트에서도 드래프트를 확인하십시오. 인덱스만 필터링하는 것은 접근 제어가 아닙니다. 요청 시점의 비공개 콘텐츠는 빌드 출력이나 공개 캐시를 통해 유출되어서는 안 됩니다.
로케일, 표준 URL 및 404 일관성
라우트를 변경하기 전에 URL 정책을 선택하십시오: 구성된 프로덕션 site, 배포 base, 후행 슬래시/빌드 형식, 로케일 접두사, 루트 동작 및 폴백 동작은 실제 파일 및 호스트 리디렉션과 일치해야 합니다.
- 폴더 기반 라우트를 사용하십시오.
prefixDefaultLocale: false인 경우 기본 언어 페이지는 루트에 있고 다른 로케일은 폴더를 갖습니다.true인 경우 모든 언어가 로케일 폴더를 가지며 루트 인덱스는 여전히 의도적인 처리가 필요합니다. - 유용한 경우 버전에서 지원하는
astro:i18n헬퍼를 사용하십시오. 구성이 콘텐츠를 번역하거나 누락된 페이지를 만들지는 않습니다. 기존 번역에만 링크하십시오. 언어 전환 시 의미 있는 동등한 경로를 유지하십시오. - 표준 URL은 프로덕션 오리진과 선택한 표준 경로명을 사용해야 하며,
Astro.url.href의 임의 요청 호스트/쿼리 매개변수를 사용해서는 안 됩니다. 배포를 위해site를 설정하고base및 후행 슬래시 정규화를 고려하십시오. 문서lang을 설정하고 상호 링크가 있는 실제 동등물에 대해서만hreflang대안을 내보내십시오. 모든 로케일을 영어로 표준화하지 마십시오. - 사용자 정의 오류 페이지가 필요할 때
src/pages/404.astro를 구현하십시오. SSR 경로에서는 성공적인 오류 본문이 아닌 실제 404 상태를 반환하십시오. 정적 호스팅에서는 생성된 404 파일이 상태 404와 함께 제공되는지 확인하십시오. 다중 페이지 사이트에 SPA 폴백을 사용하거나 누락된 모든 로케일 경로를 홈페이지로 리디렉션하지 마십시오. 오류 페이지가 색인되는 것을 방지하고 누락된 모든 URL에 자체 표준 URL을 제공하지 마십시오.
ASTRO-CANONICAL-FRAGMENT — 부분 레이아웃 예제, 독립형 페이지가 아님. site가 구성되어 있고 현재 경로명이 이미 저장소의 base/locale/slash 정책을 준수한다고 가정:
---
if (!Astro.site) throw new Error('Configure the production site URL');
const canonical = new URL(Astro.url.pathname, Astro.site);
---
<link rel="canonical" href={canonical} />
에셋 및 배포 경계
처리의 이점이 있는 이미지에는 src/assets/와 astro:assets의 Image를 선호하십시오. 변경되지 않은 URL, robots.txt 및 아이콘이 필요한 에셋은 public/에 유지하십시오. 일반 <img>는 의도적인 패스스루/원격 경우에 유효합니다. 의미 있는 alt(장식용 이미지의 경우 비움)와 고유 치수 또는 이에 상응하는 레이아웃 제약 조건을 제공하십시오. 반응형 이미지 API를 설치된 버전과 일치시키고 모든 이미지를 열심히 로드하지 말고 실제로 접힌 부분 위의 중요한 이미지만 우선시하십시오. SSR 이미지 서비스와 해당 런타임/비용 요구 사항을 활성화하기 전에 확인하십시오.
필요한 경우에만 기존 호스트의 헤더/리디렉션 메커니즘을 사용하십시오. _headers와 _redirects는 제공자별 항목이며 보편적인 Astro 요구 사항이 아닙니다. 어댑터 SSR의 경우, 수동으로 작성된 일반 정적/SPA 구성보다는 해당 어댑터 버전의 생성된 출력 및 런타임 바인딩 규칙을 따르십시오.
확인 및 보고
승인된 경우 저장소의 기존 확인/빌드/테스트 스크립트를 사용하십시오. Props 타입 지정, 내보내진 라우트, 컬렉션 검증, 드래프트 세부 페이지 노출, 로케일 전환 링크, 표준 오리진/쿼리 제거, base/slash 동작, 알 수 없는 라우트 상태, 키보드 동작 및 브라우저 콘솔 오류를 확인하십시오. 성공적인 정적 빌드가 SSR 런타임 호환성 또는 프로덕션 리디렉션을 증명하지는 않습니다. 실제로 실행된 명령, 버전 가정, 누락된 통합/콘텐츠 픽스처 및 확인되지 않은 호스팅 동작을 보고하십시오. 암시적 확인 단계로 설치, 배포 또는 원격 서비스를 트리거하지 마십시오.
출처 및 기원
이 내용은 저자의 종합이며, 타사 스킬의 대량 복사본이 아닙니다. 작업 및 설치된 버전과 관련된 문서만 읽으십시오:
- 공식 Astro: 컴포넌트 및 props, 브라우저 스크립트, 온디맨드 렌더링.
- 공식 Astro: 콘텐츠 컬렉션, Astro 5 마이그레이션, i18n 라우팅, Cloudflare 어댑터.
- astrolicious/agent-skills는 커뮤니티 참고 자료이며, 공식 Astro 문서나 호환성 보장이 아닙니다. 선택적으로 참고하십시오. 공식 버전 일치 API 문서가 우선합니다.