Chromatic 설정 가이드

이 문서는 모노레포 프로젝트에서 Chromatic을 설정하고 사용하는 방법을 설명합니다.

## 목차
- [사전 준비](#사전-준비)
- [설치 및 설정](#설치-및-설정)
- [GitHub 연동](#github-연동)
- [CI/CD 설정](#cicd-설정)
- [사용 방법](#사용-방법)
- [트러블슈팅](#트러블슈팅)

###  Chromatic 계정 생성
1. [Chromatic 웹사이트](https://www.chromatic.com/)에 접속
2. GitHub 계정으로 회원가입
3. 무료 또는 유료 플랜 선택

###  Repo 설정 
1. 반영할 프로젝트 레포지토리에 크로마틱 oauth 세팅

### create chromtic 
1. oauth 세팅시 해당과 같이 프로젝트항목이 노출됨
2. 반영할 프로젝트를 선택후 순차대로 진행 

# 세팅완료
1. 세팅완료후 정상적으로 빌드 되는지, 스토리북에 정상출력되는지 확인 

### 2. 프로젝트 요구사항
- Node.js 14.x 이상
- Storybook 6.x 이상
- Git 저장소

## 설치 및 설정

### 1. Chromatic CLI 설치
```bash
# UI 패키지에 Chromatic 설치
pnpm --filter @monorepo/ui add -D chromatic
```

### 2. 프로젝트 토큰 설정
1. Chromatic 웹사이트에서 새 프로젝트 생성
2. 제공된 프로젝트 토큰 복사
3. 환경 변수 설정:
   ```bash
   # .env 파일에 추가
   CHROMATIC_PROJECT_TOKEN=your_project_token
   ```

### 3. package.json 스크립트 추가
```json
{
  "scripts": {
    "chromatic": "chromatic --exit-zero-on-changes",
    "chromatic:ci": "chromatic --auto-accept-changes"
  }
}
```

## GitHub 연동

### 1. GitHub Actions 설정
`.github/workflows/chromatic.yml` 파일 생성:

```yaml
name: Chromatic
on: push

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Publish to Chromatic
        uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          workingDir: packages/ui
```

### 2. GitHub Secrets 설정
1. GitHub 저장소 Settings > Secrets and variables > Actions 접속
2. 'New repository secret' 클릭
3. Name: `CHROMATIC_PROJECT_TOKEN`
4. Value: Chromatic 프로젝트 토큰 입력

## 사용 방법

### 로컬에서 실행
```bash
# Storybook 실행
pnpm --filter @monorepo/ui storybook

# Chromatic에 배포
pnpm --filter @monorepo/ui chromatic
```

### UI 변경사항 검토
1. PR 생성 시 자동으로 Chromatic 빌드 실행
2. GitHub PR에 추가되는 Chromatic 링크 확인
3. 변경사항 검토 및 승인/거부

### 스냅샷 테스트
- 컴포넌트 변경 시 자동으로 스냅샷 비교
- 시각적 회귀 테스트 자동화
- 의도하지 않은 UI 변경 방지

## 트러블슈팅

### 일반적인 문제 해결
1. **빌드 실패**
   - 의존성 설치 확인
   - Node.js 버전 확인
   - 프로젝트 토큰 확인

2. **스토리 로드 실패**
   - Storybook 설정 확인
   - 컴포넌트 경로 확인
   - 필요한 의존성 설치 확인

3. **CI/CD 파이프라인 오류**
   - GitHub Actions 설정 확인
   - 환경 변수 설정 확인
   - 작업 디렉토리 경로 확인

### 모범 사례
1. **커밋 메시지 규칙**
   ```
   feat(ui): 새로운 버튼 컴포넌트 추가
   fix(ui): 버튼 스타일 수정
   chore(ui): Chromatic 설정 업데이트
   ```

2. **브랜치 전략**
   - feature/* : 새로운 기능 개발
   - fix/* : 버그 수정
   - chore/* : 설정 변경

3. **PR 템플릿**
   ```markdown
   ## 변경사항
   - [ ] UI 컴포넌트 수정
   - [ ] Storybook 문서 업데이트
   - [ ] Chromatic 스냅샷 확인

   ## 스크린샷
   [스크린샷 추가]

   ## Chromatic 링크
   [Chromatic 링크 추가]
   ```

## 참고 자료
- [Chromatic 공식 문서](https://www.chromatic.com/docs/)
- [Storybook 공식 문서](https://storybook.js.org/)
- [GitHub Actions 문서](https://docs.github.com/en/actions)