기술 스택 분석 및 Cursor 규칙 생성기

=================== --- description: 애플리케이션의 기술 스택과 버전, 그리고 모범 사례에 대한 지침 globs: alwaysApply: true --- # 페이지 UI 기술 스택 및 의존성 가이드 ## 프로젝트 개요 **페이지 UI**는 현대적인 React/Next.js 스택 기반의 랜딩 페이지 컴포넌트 라이브러리입니다: - **웹사이트**: 컴포넌트 데모가 포함된 Next.js 14 문서 사이트 - **CLI 도구**: 쉬운 프로젝트 초기화를 위한 `@ page-ui/wizard` - **컴포넌트**: Radix UI + Tailwind CSS 기반의 복사-붙여넣기 React 컴포넌트 ## 핵심 프레임워크 스택 ### **Next.js 14.2.24** (앱 라우터) - **프레임워크**: 앱 라우터 아키텍처를 갖춘 React 메타 프레임워크 - **사용 기능**: API 라우트, SSG/SSR, OG 이미지 생성, 번들 분석 - **모범 사례**: 앱 라우터 패턴 사용, pages 디렉토리 사용 지양 ### **React 18.2.0** - **UI 라이브러리**: 동시성 기능을 갖춘 핵심 React 라이브러리 - **기능**: Suspense, 자동 배칭, 서버 컴포넌트 - **모범 사례**: React 18 패턴 사용 ### **TypeScript 5.1.3** - **구성**: 더 나은 타입 안전성을 위한 strict 모드 활성화 - **모범 사례**: 최신 TS 버전 사용 ## UI 컴포넌트 시스템 ### **Radix UI 프리미티브** (v1.x 시리즈) 접근성 우선 컴포넌트 라이브러리 생태계: **모범 사례**: - 복합 컴포넌트 패턴 사용 - 인라인 스타일 대신 항상 Tailwind 클래스로 커스터마이즈 - 적절한 ARIA 속성 구현 (내장) - 일관된 스타일링을 위한 커스텀 컴포넌트로 래핑 ### **Shadcn/UI 디자인 패턴** - **위치**: `/components/shared/ui/` 디렉토리 - **철학**: NPM 의존성이 아닌 복사-붙여넣기 컴포넌트 - **스타일링**: 테마를 위한 Tailwind CSS + CSS 변수 - **변형**: 타입 안전 변형을 위한 `class-variance-authority` 사용 ## 스타일링 및 디자인 시스템 ### **Tailwind CSS 3.3.3** + 생태계 ```json { "tailwindcss": "^3.3.3", "@ tailwindcss/forms": "^0.5.4", "@ tailwindcss/typography": "^0.5.9", "tailwindcss-animate": "^1.0.7", "tailwind-merge": "^1.14.0" } ``` **모범 사례**: - 조건부 클래스에 `tailwind-merge` 사용: `cn(baseClasses, conditionalClasses)` - 테마를 위한 CSS 변수 활용: `hsl(var(--primary))` - 폼 및 타이포그래피를 위한 플러그인 사용 - 일관된 간격 및 색상 시스템 구현 ### **애니메이션 라이브러리** - **Framer Motion 10.16.4**: 복잡한 애니메이션, 페이지 전환 - **Tailwind Animate**: 간단한 CSS 애니메이션 - **모범 사례**: 간단한 효과는 CSS 애니메이션, 복잡한 상호작용은 Framer Motion 사용 ```typescript // Framer Motion 모범 사례: import { motion, AnimatePresence } from 'framer-motion' function AnimatedComponent() { return ( <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0, y: -20 }} transition={{ duration: 0.3 }} > Content </motion.div> ) } ``` ## 상태 관리 및 폼 ### **Zustand 4.5.2** (글로벌 상태) - **철학**: 최소한의, 독단적이지 않은 상태 관리 - **용도**: 테마 기본 설정, 전역 UI 상태, 컴포넌트 플레이그라운드 상태 - **모범 사례**: 적절한 셀렉터로 타입이 지정된 스토어 생성 ```typescript interface ThemeState { theme: 'light' | 'dark' setTheme: (theme: 'light' | 'dark') => void } export const useThemeStore = create<ThemeState>((set) => ({ theme: 'light', setTheme: (theme) => set({ theme }), })) ``` ### **React Hook Form 7.46.2** + 검증 - **폼 라이브러리**: 성능이 뛰어난, 비제어 폼 - **검증**: `@ hookform/resolvers` ^3.3.1 + `zod` ^3.22.2 - **통합**: Radix UI 폼 컴포넌트와 원활하게 작동 ```typescript // 모범 사례 폼 설정: const formSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) function ContactForm() { const form = useForm<z.infer<typeof formSchema>>({ resolver: zodResolver(formSchema), }) return <form onSubmit={form.handleSubmit(onSubmit)}>...</form> } ``` ### **Zod 3.22.2** (스키마 검증) - **용도**: 폼 검증, API 응답 검증, 타입 생성 - **모범 사례**: 사용처 근처에 스키마 정의, 타입 추론 활용 ## 콘텐츠 관리 시스템 ### **커스텀 Contentlayer 구현** ```json { "@ shipixen/next-contentlayer-module": "1.0.2", "shipixen-contentlayer": "1.0.2", "@ shipixen/pliny": "1.0.13" } ``` **기능**: - 타입 안전 MDX 처리 - Frontmatter 파싱 - 자동화된 콘텐츠 가져오기 - RSS 피드 생성 ### **MDX 처리 파이프라인** **Remark 플러그인** (Markdown 처리): - `remark-gfm` ^3.0.1: GitHub 플레이버 Markdown - `remark-math` ^5.1.1: 수식 표현 **Rehype 플러그인** (HTML 처리): - `rehype-slug` ^5.1.0: 제목 ID 자동 생성 - `rehype-autolink-headings` ^6.1.0: 제목 자동 링크 - `rehype-prism-plus` ^1.6.1: 구문 강조 - `rehype-katex` ^6.0.3: 수식 렌더링 **모범 사례**: - 콘텐츠는 런타임이 아닌 빌드 시간에 처리 - 안정적인 빌드를 위해 일관된 플러그인 버전 사용 - 생성된 타입으로 타입 안전 콘텐츠 쿼리 ## 개발 경험 ### **코드 품질 도구** ```json { "eslint": "^8.45.0", "@ typescript-eslint/eslint-plugin": "^6.1.0", "@ typescript-eslint/parser": "^6.1.0", "eslint-config-next": "^14.2.24", "eslint-config-prettier": "^8.8.0", "prettier": "^3.0.0", "prettier-plugin-tailwindcss": "^0.4.1" } ``` **Git 워크플로우**: - **Husky 8.0.0**: Git 후크 자동화 - **lint-staged 13.0.0**: 커밋 전 린팅 및 포맷팅 ### **인터랙티브 개발 도구** - **Monaco Editor 0.45.0**: 컴포넌트 플레이그라운드를 위한 브라우저 내 코드 편집 - **명령 팔레트**: 전역 검색 및 탐색을 위한 `cmdk` ^0.2.0 - **번들 분석기**: 성능 모니터링을 위한 `@ next/bundle-analyzer` ## CLI 도구 (@ page-ui/wizard) ### **패키지 구성** ```json { "name": "@ page-ui/wizard", "type": "module", "bin": "./packages/cli/index.mjs", "engines": { "node": ">=14.17.0" } } ``` ### **CLI 의존성** ```json { "chalk": "^5.3.0", // 터미널 색상 및 스타일링 "commander": "^12.0.0", // 커맨드 라인 인터페이스 프레임워크 "enquirer": "^2.4.1", // 인터랙티브 CLI 프롬프트 "ora": "^8.0.1" // CLI용 로딩 스피너 } ``` **모범 사례**: - ESM 모듈 사용 (`.mjs` 확장자) - enquirer로 인터랙티브 프롬프트 제공 - ora 스피너로 진행 상황 표시 - chalk로 일관된 터미널 스타일링 ## 분석 및 외부 서비스 ### **Vercel 생태계** - **분석**: `@ vercel/analytics` ^1.1.1 - **OG 이미지**: `@ vercel/og` ^0.5.20 - **모범 사례**: 최적의 성능을 위해 Vercel 네이티브 도구 사용 ### **제품 분석** - **PostHog 1.130.1**: 기능 플래그, 사용자 추적, A/B 테스트 - **모범 사례**: 적절한 동의 관리로 프라이버시 준수 설정 ### **HTTP 클라이언트** - **Axios 1.7.7**: API 호출, 뉴스레터 구독 - **모범 사례**: 기본 구성으로 axios 인스턴스 생성 ## 유틸리티 라이브러리 ### **날짜 및 시간** - **date-fns 2.30.0**: 모듈형 날짜 유틸리티 라이브러리 - **모범 사례**: 트리 셰이킹을 위해 필요한 함수만 가져오기 ```typescript // 좋음: 트리 셰이킹 가능한 가져오기 import { format, parseISO } from 'date-fns' // 나쁨: 전체 라이브러리 가져오기 import * as dateFns from 'date-fns' ``` ### **스타일링 및 UI 유틸리티** - **clsx 2.0.0**: 조건부 className 유틸리티 - **class-variance-authority 0.7.0**: 타입 안전 컴포넌트 변형 - **chroma-js 2.4.2**: 색상 조작 및 테마 생성 ### **데이터 표시** - **@tanstack/react-table 8.10.7**: 강력한 테이블 컴포넌트 - **lucide-react 0.400.0**: 아이콘 라이브러리 - **sonner 1.3.1**: 토스트 알림