create-react-shadcn-app/README.md

CLI tool to create React applications with shadcn/ui components

# 🚀 create-react-shadcn-app

React + shadcn/ui 애플리케이션을 빠르게 생성하는 CLI 도구

## 📦 사용 가능한 템플릿

### 1. 🔥 React + Vite
**템플릿명**: `react-vite`

빠른 개발을 위한 Vite와 타입 안전한 라우팅을 위한 TanStack Router가 포함된 현대적인 React 보일러플레이트입니다.

**기술 스택**:
- React 19 + TypeScript
- Vite (빌드 도구)
- TanStack Router (타입 안전한 라우팅)
- Tailwind CSS v4
- shadcn/ui 컴포넌트
- Jotai (상태 관리)
- TanStack Query (서버 상태)

### 2. ⚡ Next.js App Router
**템플릿명**: `nextjs-app-router`

서버 컴포넌트와 스트리밍을 지원하는 현대적인 App Router를 사용한 Next.js 보일러플레이트입니다.

**기술 스택**:
- Next.js 15 + App Router
- TypeScript
- Tailwind CSS v4
- shadcn/ui 컴포넌트
- Jotai (상태 관리)
- TanStack Query (서버 상태)

### 3. 📄 Next.js Pages Router
**템플릿명**: `nextjs-pages-router`

전통적인 Pages Router를 사용한 Next.js 보일러플레이트입니다. 기존 프로젝트나 특정 요구사항이 있는 경우에 적합합니다.

**기술 스택**:
- Next.js 15 + Pages Router
- TypeScript
- Tailwind CSS v4
- shadcn/ui 컴포넌트
- Jotai (상태 관리)
- TanStack Query (서버 상태)

## 🚀 빠른 시작

### npx 사용 (권장)

```bash
# React + Vite 프로젝트 생성
npx create-react-shadcn-app react-vite my-app

# Next.js App Router 프로젝트 생성
npx create-react-shadcn-app nextjs-app-router my-dashboard

# Next.js Pages Router 프로젝트 생성
npx create-react-shadcn-app nextjs-pages-router my-blog
```

### 전역 설치 후 사용

```bash
# 전역 설치
npm install -g create-react-shadcn-app

# 프로젝트 생성
create-react-shadcn-app react-vite my-app
create-react-shadcn-app nextjs-app-router my-dashboard
create-react-shadcn-app nextjs-pages-router my-blog
```

### degit 사용 (대안)

```bash
# 템플릿을 직접 복사
npx degit im-ian/create-react-shadcn-app/packages/react-vite my-app
npx degit im-ian/create-react-shadcn-app/packages/nextjs-app-router my-dashboard
npx degit im-ian/create-react-shadcn-app/packages/nextjs-pages-router my-blog

# 의존성 설치 및 개발 서버 시작
cd my-app
npm install
npm run dev
```

## 🛠️ 공통 기능

모든 템플릿에 포함된 기능:

- ✅ **TypeScript** 타입 안전성
- ✅ **Tailwind CSS v4** 현대적인 스타일링
- ✅ **shadcn/ui** Tailwind 기반의 UI 컴포넌트
- ✅ **Jotai** 원자적 상태 관리
- ✅ **TanStack Query** 서버 상태 관리
- ✅ **ESLint** 코드 품질 관리
- ✅ **도메인 기반 폴더 구조**
- ✅ **현대적인 개발 도구**

## 📁 프로젝트 구조

각 템플릿은 일관된 도메인 기반 구조를 따릅니다:

```
src/
├── components/             # 공유/공통 컴포넌트
│   └── ui/                # shadcn/ui 컴포넌트
├── domains/               # 도메인 기반 구성
│   ├── user/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── index.ts
│   ├── product/
│   └── order/
├── hooks/                 # 공유 훅
├── lib/                   # 유틸리티 및 설정
└── ...                    # 프레임워크별 파일
```

## 🎯 각 템플릿 사용 시기

### React + Vite
- **적합한 용도**: SPA, 클라이언트 사이드 애플리케이션, 빠른 프로토타이핑
- **장점**: 빠른 개발, 간단한 배포, 완전한 클라이언트 사이드 제어
- **사용 사례**: 대시보드, 관리자 패널, 인터랙티브 웹 앱

### Next.js App Router
- **적합한 용도**: 풀스택 애플리케이션, SEO가 중요한 사이트, 현대적인 React 패턴
- **장점**: 서버 컴포넌트, 스트리밍, 내장 최적화, SEO 친화적
- **사용 사례**: 마케팅 사이트, 이커머스, 블로그, 복잡한 웹 애플리케이션

### Next.js Pages Router
- **적합한 용도**: 기존 Next.js 프로젝트, 점진적 마이그레이션, 특정 요구사항
- **장점**: 성숙한 생태계, 잘 문서화됨, 안정적인 API
- **사용 사례**: 레거시 프로젝트, 특정 라우팅 요구사항, 점진적 도입

## 🔧 커스터마이징

### 컴포넌트 추가

모든 템플릿은 shadcn/ui를 사용합니다. 새 컴포넌트 추가:

```bash
npx shadcn@latest add [컴포넌트명]
```

### 상태 관리

- **클라이언트 상태**: Jotai atoms 사용
- **서버 상태**: TanStack Query 사용
- **폼 상태**: react-hook-form (필요시 추가)

### 스타일링

- `globals.css`에서 Tailwind CSS 커스터마이징
- shadcn/ui 테마 변수 수정
- `components/ui/`에 커스텀 컴포넌트 추가

## 📝 스크립트

각 템플릿에 포함된 공통 스크립트:

```bash
npm run dev      # 개발 서버 시작
npm run build    # 프로덕션 빌드
npm run lint     # ESLint 실행
npm run preview  # 프로덕션 빌드 미리보기 (Vite만)
npm run start    # 프로덕션 서버 시작 (Next.js만)
```

## 🚀 배포

### React + Vite
- **권장**: Vercel, Netlify, GitHub Pages
- **빌드**: `npm run build` → `dist/` 폴더

### Next.js (App Router & Pages Router)
- **권장**: Vercel (제로 설정)
- **대안**: Netlify, AWS, Docker
- **빌드**: `npm run build` → `.next/` 폴더

## 🤝 기여하기

1. 저장소 포크
2. 기능 브랜치 생성 (`git checkout -b feature/amazing-feature`)
3. 변경사항 커밋 (`git commit -m 'Add some amazing feature'`)
4. 브랜치에 푸시 (`git push origin feature/amazing-feature`)
5. Pull Request 열기

## 📄 라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다.

---

**빠르게 시작하고 멋진 앱을 만들어보세요! 🎉**