Storybook 배포 자동화: Chromatic with GitHub Actions

서론

Storybook은 UI 컴포넌트를 독립적으로 개발하고 테스트할 수 있는 강력한 도구다. 그런데 개발만큼 중요한 게 바로 공유와 협업이다. 개발한 컴포넌트를 디자인팀이나 PM이 바로 확인할 수 있어야 하고, 수정이 필요한 부분이 있으면 빠르게 피드백을 주고받을 수 있어야 한다.

보통 이런 정적 웹페이지를 배포하려면 Vercel이나 Netlify 같은 호스팅 서비스를 사용하면 된다. 하지만 Storybook에 특화된 배포 솔루션이 있다면 더 편하지 않을까? Chromatic을 통해 Storybook을 배포해보자!

Storybook + Chromatic 조합은 어떤게 좋을까❓

1. 배포가 자동으로 된다
Chromatic을 설정하면 GitHub에 코드만 푸시해도 Storybook이 자동으로 배포된다. 따로 빌드하고 배포하는 과정 없이, 개발자가 코드를 수정하면 변경된 UI가 바로 적용된 Storybook을 볼 수 있다.

2. 시각적 테스트 (Visual Test) 지원
코드를 수정할 때 UI가 깨지는 경우가 많다. 그런데 작은 디자인 변화가 코드 레벨에서는 티가 잘 안 나서 놓치는 경우도 있다. Chromatic은 비교 기능을 제공해서, 변경 전후 UI를 이미지로 비교해준다. 덕분에 예상치 못한 디자인 깨짐(Regression)도 쉽게 발견할 수 있다.

3. 디자인팀과 협업이 편리하다
Chromatic은 단순히 배포만 되는 게 아니라, 디자인팀이 직접 확인하고 댓글도 남길 수 있다. 예를 들어 버튼 색상이 마음에 안 들면 Storybook에서 바로 피드백을 남길 수 있다. 개발팀은 이 피드백을 보고 바로 수정하면 된다. 따로 Figma 캡처해서 공유할 필요 없이, 실시간으로 의견을 주고받을 수 있는 거다.

4. 접근성이 좋다
배포된 Storybook 링크만 있으면 누구나 접속해서 확인할 수 있다. 개발팀뿐만 아니라 기획자, 마케터, QA팀도 바로 들어와서 보면서 의견을 줄 수 있다. UI 검토 과정이 훨씬 매끄러워진다.

Storybook과 Chromatic을 같이 쓰면 배포, 시각적 테스트, 피드백, 협업이 한 번에 해결된다. 개발팀도 편하고, 디자인팀도 편하고, 결국 서비스 품질까지 올라간다. 그래서 Storybook을 쓰는 팀이라면 Chromatic을 같이 쓰는 걸 강력 추천한다! 🚀

Chromatic으로 Storybook 배포하는 방법 🚀

0.Chromatic Chromatic 와 Github Repository 연동

0.1 깃허브 계정으로 chromatic에 가입한다.

0.2 Choose Github Repo 버튼을 눌러 Github Repository와 동기화 한다.

0.3 프로젝트 설정을 Storybook으로 선택한다.

0.4 고유한 project-token을 복사해준다.

1. 프로젝트에 Chromatic 설치

• Storybook 프로젝트에 Chromatic 패키지를 설치한다.
• 설치를 위해 아래 명령어를 입력한다.
• npm install --save-dev chromatic

2. Chromatic에 프로젝트 연결

• Storybook 프로젝트를 Chromatic에 연결하려면 아래 명령어를 실행한다.

• npx chromatic --project-token=<your-project-token>

• 여기서 <your-project-token>은 아까 복사한 고유한 token 값을 사용하면 된다.

• 명령어 실행 후 아래와 같은 메시지가 나타나는데, 여기서 y를 입력하면 package.json의 scripts에 chromatic 명령어가 추가된다.

⚠ No 'chromatic' script found in your package.json  
Would you like me to add it for you? [y/N]

3. Storybook 빌드 후 Chromatic에 배포

• 이제 Storybook을 빌드하고 Chromatic에 배포를 한다.
• npx chromatic

이 명령어를 실행하면:
1. Storybook이 빌드됨
2. Chromatic 서버에 배포됨
3. 공유 가능한 URL이 생성됨

• 빌드가 완료되면 Chromatic 페이지에서 배포된 결과를 확인할 수 있다.
• 이제 해당 URL을 디자인팀이나 다른 팀원들에게 공유하면 끝이다!!!

GitHub Actions 사용하여 배포 자동화하기🚀

Chromatic을 GitHub Actions과 연동하면, 코드가 변경될 때마다 Storybook을 자동으로 배포할 수 있다. 이렇게 하면 배포 과정을 수동으로 실행할 필요 없이 항상 최신 UI를 유지할 수 있다.

1.GitHub Chromatic Token 생성

먼저, GitHub Actions에서 Chromatic을 실행할 수 있도록 Chromatic Token을 GitHub Secrets에 추가해야 한다.

1. Chromatic Dashboard에서 프로젝트의 project-token을 확인한다.

2. GitHub 저장소로 이동하여 Settings > Secrets and variables > Actions 로 들어간다.

3. New repository secret을 클릭하고:

• Name: CHROMATIC_PROJECT_TOKEN(다른 변수명으로 해도 됨)

• Value: 아까 복사한 project-token 값 입력

• Add secret 버튼 클릭

이제 GitHub Actions에서 사용할 준비가 완료되었다.

2.GitHub Actions Workflow 생성

GitHub Actions에서 Storybook을 자동으로 배포하려면, .github/workflows/chromatic.yml 파일을 만들어야 한다.

📌 chromatic.yml 파일 생성

name: 'Deploy Storybook to Chromatic'

on:
  push:
    branches:
      - main  # main 브랜치에 푸시될 때 실행
  pull_request:
    branches:
      - main  # PR이 생성될 때 실행

env:
  CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

jobs:
  chromatic-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install dependencies
        run: npm install

      - name: Build Storybook
        run: npm run build-storybook

      - name: Publish to Chromatic
        run: npx chromatic --project-token=${{ secrets.CHROMATIC_PROJECT_TOKEN }}

3. GitHub Actions 실행 확인

이제 main 브랜치에 코드가 푸시되거나 PR이 생성되면 자동으로 Chromatic에 Storybook이 배포된다. 실행 결과는 GitHub Actions의 Actions 탭에서 확인할 수 있다.

• ✅ 성공하면 Storybook이 배포된 URL이 표시됨

• ❌ 실패하면 로그를 보고 수정하면 됨

출처

https://storybook.js.org/tutorials/intro-to-storybook/react/ko/deploy/