Astro v6 아키텍처 규칙 (엄격 모드)

# Astro v6 아키텍처 규칙 (엄격 모드) ## 1. 핵심 철학 - Astro의 "HTML 우선 / 기본적으로 제로 자바스크립트" 원칙을 따를 것: - 상호작용이 명시적으로 요구되지 않는 한 모든 것은 정적 HTML이다. - 자바스크립트는 비용이며, 실제 사용자 가치를 창출할 때만 추가한다. - 항상 "아일랜드 아키텍처"로 사고할 것: - 페이지는 정적 HTML이다. - 상호작용 부분은 격리된 아일랜드이다. - 전체 페이지를 앱으로 취급하지 말 것. - 자바스크립트를 작성하기 전에 항상 "이것이 HTML + CSS 또는 서버 측 로직으로 해결될 수 있는가?"라고 질문할 것. ## 2. 컴포넌트 모델 - 다음 용도로 `.astro` 컴포넌트를 사용할 것: - 레이아웃 - 구성 - 정적 UI - 데이터 가져오기 - 서버 측 로직 (frontmatter) - `.astro` 컴포넌트: - 빌드 시 또는 서버 측에서 실행된다. - 기본적으로 자바스크립트를 제공하지 않는다. - 프레임워크에 구애받지 않아야 한다. - `.astro` 내부에서 React/Vue/Svelte 훅을 절대 사용하지 말 것. ## 3. 아일랜드 (상호작용 컴포넌트) - 상호작용에만 프레임워크 컴포넌트(React, Vue, Svelte 등)를 사용할 것. - 모든 상호작용 컴포넌트를 격리된 아일랜드로 취급할 것: - 독립적 - 자체 포함 - 최소 범위 - 절대 하지 말 것: - 전체 페이지 또는 레이아웃을 하이드레이션 - 큰 트리를 단일 아일랜드로 감싸기 - 루프에서 불필요하게 많은 작은 아일랜드 생성 - 선호할 것: - 정적 목록 렌더링 - 최소 상호작용 단위만 하이드레이션 ## 4. 하이드레이션 전략 (중요) - 항상 `client:*` 지시문을 사용하여 하이드레이션을 명시적으로 정의할 것. - 가능한 가장 낮은 우선순위를 선택할 것: - `client:load` -> 중요하고 화면 상단에 보이는 상호작용에만 사용 - `client:idle` -> 페이지 로드 후 보조 UI에 사용 - `client:visible` -> 화면 아래 또는 무거운 컴포넌트에 사용 - `client:media` -> 반응형 / 조건부 UI에 사용 - `client:only` -> SSR이 실패할 때만 사용 (window, localStorage 등) - 기본 규칙: - `client:load`를 기본값으로 사용하지 말 것 - `client:visible` 또는 `client:idle`을 선호할 것 - 하이드레이션은 성능 예산이다: - 모든 아일랜드는 JS를 추가한다. - 총 JS를 최소로 유지할 것. ## 5. 서버 vs 클라이언트 로직 - 다음 용도로 서버 측 로직(`.astro` frontmatter 내부)을 선호할 것: - 데이터 가져오기 - 변환 - 필터링 / 정렬 - 파생 값 - 다음 경우에만 클라이언트 측 상태를 사용할 것: - 사용자 상호작용이 요구할 때 - 실시간 업데이트가 필요할 때 - 피할 것: - 클라이언트에서 로직 중복 - 서버 로직을 아일랜드로 이동 ## 6. 상태 관리 - 꼭 필요한 경우가 아니면 클라이언트 상태를 피할 것. - 필요한 경우: - 상태를 아일랜드 내부로만 한정할 것 - 요구되지 않는 한 전역 앱 상태를 만들지 말 것 - 아일랜드 간 상태: - 가벼운 공유 스토어(예: nano stores)를 사용할 것 - 기본적으로 무거운 전역 상태 시스템을 피할 것 ## 7. 성능 제약 (하드 규칙) - 클라이언트로 전송되는 자바스크립트 최소화: - Astro는 하이드레이션된 컴포넌트에만 JS를 로드한다. - 선호할 것: - 정적 렌더링 - 부분 하이드레이션 - 지연 하이드레이션 - 피할 것: - 큰 목록 하이드레이션 - 루프에서 반복되는 아일랜드 - `client:load` 과다 사용 - 각 아일랜드: - 자체 번들을 가진다. - 독립적으로 로드된다. - 작고 집중된 상태를 유지해야 한다. ## 8. 파일 및 프로젝트 구조 - `/pages` - 진입점 (SSG/SSR), 클라이언트 로직 없음 - `/components` - 공유 UI, 아일랜드는 여기에 위치 - `/layouts` - 정적 래퍼만 - `/content` - 마크다운 / CMS 데이터 - `.astro` 파일을 동작이 아닌 구성에 집중하도록 유지할 것. ## 9. 안티 패턴 (엄격히 금지) - `.astro`에서 훅 사용 - Astro를 SPA 아키텍처로 전환 - 전체 레이아웃/페이지 하이드레이션 - 모든 곳에서 `client:load` 사용 - 목록을 하이드레이션된 컴포넌트로 매핑 - 정적 문제에 클라이언트 JS 사용 - 서버 로직을 클라이언트 로직으로 대체 ## 10. 선호 패턴 - 정적 우선 렌더링 - 최소, 격리된 아일랜드 - 지연 하이드레이션 (`visible`, `idle`) - 서버 측 계산 - JS 전에 HTML + CSS - 점진적 향상 ## 11. 결정 프레임워크 (매우 중요) 모든 기능에 대해: 1. 이것이 정적 HTML이 될 수 있는가? -> 예 -> `.astro` 사용 2. 상호작용이 필요한가? -> 아니요 -> 정적으로 유지 3. JS가 필요한가? -> 예 -> 아일랜드 생성 4. 언제 로드되어야 하는가? -> 가장 낮은 우선순위 `client:*` 선택 ## 12. 정신 모델 (불가협상) - Astro는 아니다: - Next.js - SPA 프레임워크 - React 우선 시스템 - Astro는 이다: - 정적 우선 렌더러 - 부분 하이드레이션 시스템 - 성능 우선 아키텍처 - 생각할 것: "HTML을 제공하고 JS를 뿌린다"