Communitygithub.com

five-angles-company/convex-starter

Astro 마케팅 사이트(apps/landing)에서 작업합니다. 랜딩 페이지 편집, 섹션/컴포넌트 추가, Astro에서 shadcn/@workspace/ui 사용, Tailwind v4 스타일링, 랜딩에 동적 데이터 추가 시 사용하세요. 제로-JS 모델, .astro 파일을 위한 Tailwind @source 수정, 정적 사이트를 위한 Convex 패턴을 설명합니다.

convex-starter란 무엇인가요?

이 스킬은 `apps/landing` 디렉토리에 있는 Astro 기반 마케팅 랜딩 페이지 개발을 위한 가이드입니다. `@workspace/ui`(shadcn/Tailwind v4)를 재사용하여 브랜드 일관성을 유지하고, 거의 제로 클라이언트 JS로 정적 HTML을 생성합니다. Next.js 앱이나 모바일과는 다른 런타임을 가지므로 이 스킬은 오직 랜딩 페이지 변경에만 사용해야 합니다. 주요 특징으로는 Astro의 기본 정적 렌더링 모델, Tailwind v4에서 `.astro` 파일의 유틸리티 클래스 생성을 위한 `@source` 지시어 수정, 동적 데이터가 필요할 때 `ConvexHttpClient`를 사용하는 방법을 포함합니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트에서 랜딩 페이지 관련 작업을 정확하고 효율적으로 수행하도록 돕습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/five-angles-company/convex-starter/tree/HEAD/.claude/skills/astro-landing

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

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

문서

랜딩 (Astro)

apps/landing은 정적 Astro 사이트로, @workspace/ui(shadcn / Tailwind v4)를 재사용하여 브랜드 일관성을 유지하며, 클라이언트 JS가 거의 없습니다.

사용 시기

  • apps/landing 아래의 모든 변경 사항: 섹션, 컴포넌트, 스타일링 또는 동적 데이터 추가.

사용하지 말아야 할 때

  • Next.js 앱이나 모바일 — 다른 런타임을 사용합니다.

제로-JS 모델

  • Astro는 React 컴포넌트를 기본적으로 빌드 시 정적 HTML로 렌더링합니다. shadcn 컴포넌트(<Button>, <Card>, <Badge>)를 프레젠테이션 용도로 사용하면 클라이언트 JS가 전혀 전송되지 않습니다.
  • client:* 지시문(client:load, client:visible)을 추가한 경우에만 JS가 전송됩니다. 진정한 상호작용이 필요한 부분에만 사용하고, 해당 상호작용 그룹은 단일 .tsx 아일랜드로 유지하세요. React 컨텍스트는 별도의 Astro 아일랜드 간에 공유되지 않습니다.
  • 버튼처럼 스타일링된 링크는 하이드레이션된 버튼 대신 <a class={buttonVariants(...)}>을 선호합니다.

Tailwind v4 + 공유 토큰 (핵심 수정 사항)

  • Tailwind v4는 astro.config.mjs에서 @tailwindcss/vite를 통해 연결됩니다 (이전 @astrojs/tailwind 통합은 더 이상 사용되지 않음).
  • src/styles/global.css는 공유 테마를 가져오고 Astro 콘텐츠 소스를 추가합니다:
    @import "@workspace/ui/globals.css";
    @source "./**/*.{astro,ts,tsx}";
    
    공유 globals.css는 .ts/.tsx만 스캔하므로, 추가된 @source 없이 .astro 마크업에 작성된 유틸리티 클래스는 생성되지 않습니다 (조용히 적용되지 않습니다).
  • CSS-주석 함정: **/ glob을 포함하는 CSS 주석(예: apps/**/* 설명)은 주석을 일찍 종료(*/)시켜 다음 규칙을 손상시킵니다. 주석에 glob을 넣지 마세요.

동적 데이터 (필요한 경우)

  • 랜딩에는 React 프로바이더나 WorkOS 인증이 없습니다. 양식/동적 호출을 위해서는 ConvexHttpClient (convex/browser에서)를 사용하는 Astro 서버 엔드포인트를 사용하여 일회성 변이/쿼리를 수행하세요. ConvexReactClient/ConvexProviderWithAuth를 사용하지 마세요.

주의사항

  • 전체 @workspace/ui/globals.css를 가져오면 추가 테마 변수/애니메이션이 포함됩니다 — 괜찮습니다 (Tailwind가 사용하지 않는 유틸리티를 트리 쉐이킹합니다).
  • 여기에는 next-themes가 없으므로, 작은 인라인 .dark 토글 스크립트를 추가하지 않는 한 랜딩은 라이트 전용입니다.
  • next/font를 사용할 수 없습니다 — 정확한 글꼴 일치를 위해 @fontsource/* 또는 <link>를 사용하세요.

확인

  • pnpm --filter landing build → 정적 dist/; client:*가 없는 페이지의 index.html에는 <script> 태그가 없습니다.
  • .astro에서만 사용된 클래스(예: bg-primary)가 빌드된 CSS에 나타납니다 (@source 수정이 작동함).
  • pnpm --filter landing typecheck (astro check)가 통과합니다.

관련 스킬