Chromatic으로 Storybook자동배포 사용법

울랄라신나·2025년 6월 30일

chromatic storybook

그냥 내가 사용해 본 것들

목록 보기

7/12

참고사이트
Storybook Chromatic 으로 배포하기
Storybook Tutorials

📌 목차

Chromatic이란?
초기 세팅
Github Action으로 Chromatic 자동 배포
배포 테스트
회고

Chromatic이란?

Chromatic은 Storybook과 밀접하게 연관된 클라우드 기반 도구입니다. UI 컴포넌트의 시각적 테스트와 버전 관리를 돕는 도구로, Storybook을 클라우드에서 관리하고 자동화된 시각적 회귀 테스트를 진행할 수 있다. 이를 통해 프로젝트의 UI가 시간이 지나면서 의도하지 않은 방식으로 변경되지 않도록 보장할 수 있다.

주요 기능은 다음과 같다:

시각적 회귀 테스트(Visual Regression Testing): 컴포넌트의 변경 사항을 자동으로 감지하고 이전 버전과 비교하여 UI에 의도치 않은 변화가 있는지 확인한다.
UI 버전 관리: 다양한 버전의 UI 컴포넌트를 관리하고, 팀원들과 쉽게 공유할 수 있다.
팀 협업: Storybook에서 컴포넌트를 실시간으로 확인하고, 피드백을 주고받는 기능을 지원한다.

Chromatic 설치 및 사용법

Chromatic 설치

Chromatic은 Storybook과 함께 사용됩니다. 먼저 chromatic을 설치해야 한다.
```
npm install --save-dev chromatic
```
Chromatic 계정 연결

Chromatic을 사용하려면 Chromatic 계정이 필요합니다. Chromatic 웹사이트에 가입하고 프로젝트를 생성한다.

계정 생성 후 project token을 받게 됩니다. 이 토큰을 이용해 프로젝트를 연결할 수 있다.
Chromatic 실행

프로젝트에서 Chromatic을 실행하려면, 아래 명령어를 통해 Storybook을 빌드하고 Chromatic에 업로드한다.
```
npx chromatic --project-token <your_project_token>
```
이 명령어는 Storybook을 빌드하고, 해당 빌드 파일을 Chromatic에 업로드하여 시각적 테스트를 진행한다. Chromatic은 이전 버전과 비교하여 UI의 변화가 있는지 자동으로 검사한다.
시각적 회귀 테스트 및 협업
- 변경 사항 검토: Chromatic 대시보드에서 컴포넌트의 시각적 변경 사항을 검토할 수 있습니다. UI가 이전 상태와 어떻게 달라졌는지 확인하고, 필요하다면 변경을 승인하거나 거절할 수 있다.
- 피드백 주기: 팀원들이 변경 사항에 대해 피드백을 주고받을 수 있으며, 각 변경에 대한 설명을 추가할 수 있다.

Storybook + Chromatic 워크플로우 예시

Storybook을 로컬에서 개발
- UI 컴포넌트를 Storybook에서 개발하고, 다양한 상태를 스토리로 작성한다.
Chromatic에 업로드
- Storybook을 Chromatic에 업로드하여 시각적 회귀 테스트를 실행한다.
시각적 회귀 테스트 결과 확인
- Chromatic 대시보드에서 UI 변경 사항을 확인하고, 문제점을 발견하면 롤백하거나 수정한다.
팀과 협업
- 변경 사항에 대해 팀원들과 협업하고 피드백을 주고받으며, 최종적으로 승인된 변경 사항만 배포한다.

마무리

Storybook은 UI 컴포넌트의 개발과 테스트를 독립적으로 할 수 있게 도와주는 도구이며, Chromatic은 Storybook의 시각적 회귀 테스트와 팀 협업을 위한 클라우드 기반 서비스이다.
Storybook은 로컬 개발에서 유용하게 사용되고, Chromatic은 이를 클라우드에서 관리하며 시각적 테스트와 버전 관리에 도움을 준다.

이 두 도구를 결합하면 React 애플리케이션의 UI 컴포넌트를 효율적으로 개발하고 유지보수할 수 있다.

Storybook은 UI 개발을 위한 도구로, 구성 요소를 분리하여 개발을 더욱 빠르고 쉽게 만들어준다. Storybook을 사용하면 한 번에 한 구성 요소를 독립적으로 개발할 수 있으며, 복잡한 데이터베이스나 백엔드와 연결할 필요 없이 UI를 효율적으로 설계할 수 있다.

Storybook의 또 다른 주요 장점은 Figma와의 연동이다. 이를 통해 디자이너와 개발자가 동일한 디자인 사양을 공유하고, Storybook에서 구현된 UI와 Figma의 디자인 파일 간의 시각적 일치를 쉽게 검토할 수 있다. 이러한 연동은 디자인-개발 간 협업 효율성을 높이고, 디자인 시스템을 유지보수하거나 확장하는 데 큰 도움이 된다.

초기 세팅

Chromatic 가입

Github Actions을 사용할 예정이니, 당연히 Github로 로그인하면 된다.

storybookTutorials

배포할 프로젝트 연동

크로마틱 설치
```
// npm
npm install --save-dev chromatic

// yarn
yarn add -D chromatic
```
본인이 사용하는 패키지 매니저에 맞게 설치하면된다.
Storybook을 Chromatic에 배포

프로젝트에 대해 생성된 고유한 것을 복사합니다 . 그런 다음 명령줄에서 다음을 실행하여 Storybook을 빌드하고 배포합니다. 프로젝트 토큰으로 project-token바꿔야 한다.

project-token

위 사진 중 두 번째 코드를 복사해서 붙여넣기 하면 된다. 참고로 가려진 부분이 해당 프로젝트의 chromatic 토큰이다.

npx chromatic --project-token=<<크로마틱 토큰>> 또는
yarn chromatic --project-token=<project-token>

그러면 이렇게 설치가 된다.

위 화면이 뜨면 정상적으로 배포가 완료된 것이다.

⚠ 추가 작업 (선택 사항)

마지막에 "No 'chromatic' script found in your package.json" 라는 메시지가 떴어.

이건 package.json에 "scripts" 안에 chromatic 명령어가 없다는 뜻이야.

자동으로 추가할지 묻고 있는데, "y" 입력하면 추가 가능함.

만약 수동으로 추가하고 싶다면, package.json에 아래 코드 넣어주면 끝

package.json 파일

"scripts": {
  "chromatic": "npx chromatic --project-token=chpt_bca879eca6336d3"
}

설치 및 실행 성공 확인

Authenticated with Chromatic → 인증 완료
Storybook built in 10 seconds → Storybook 정상적으로 빌드됨
Publish complete in 8 seconds → Storybook이 Chromatic에 업로드됨
Build passed. Welcome to Chromatic! → 모든 테스트 및 스냅샷이 정상적으로 생성됨
🔗 배포된 Storybook 링크:

스토리북 도입 이전 문제점
1. 코드를 보고 컴포넌트를 떠올리기 어려움

PR을 꼼꼼하게 작성하고 읽는데 사용하는 불필요하게 높은 소통 비용

컴포넌트의 UI와 테스트를 위해 직접 실행해봐야하는 불편함

🤔 Pull Requset에서 컴포넌트 UI를 확인할 수 없을까?

하지만 아직 스토리북 도입 이전의 문제점 중 마지막 문제점인 컴포넌트의 UI와 테스트를 위해 직접 실행해봐야하는 불편함에 대해서는 해결하지 못했다. 스토리북을 도입했지만 여전히 아래와 같은 불편함이 발생하고 있었다.

코드를 pull 받고 → 스토리북을 로컬에서 실행하고 → 컴포넌트가 제대로 작동하는지 확인

이러한 불편함을 해결하기 위해 PR로 올라온 컴포넌트 변경사항을 배포된 환경에서 확인할 수 있도록 Github Action을 추가해보겠다.

🚀

Github Action으로 Chromatic 자동 배포

참고자료
Automate Chromatic with GitHub Actions • Chromatic docs

git action 프로세스

chroatic.yml → github Secret → git push → 자동 배포

Chromatic 토큰 등록

해당 프로젝트의 Settings의 Secrets and variables 안에 actions를 클릭하면 위 화면이 나오는데, 여기서 New repository secret을 클릭하면,
아래와 같은 화면이 나온다 여기서, 원하는 토큰명을 작성하고, Secret* 안에 크로마틱 토큰을 넣어주면된다.
./github/workflows/storybook.yml 폴더 생성

프로젝트의 루트 경로에 ./github/workflows/storybook.yml 폴더를 생성

Github Action 코드 작성

전체코드

name: 'Chromatic'

# on: push
on:
  push:
    branches:
      - main # main 브랜치에 푸시할 때 실행

jobs:
  chromatic:
    name: Run Chromatic
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 모든 Git 히스토리를 가져옴 (Chromatic이 변경사항을 감지하는 데 필요)

      - uses: actions/setup-node@v4
        with:
          node-version: 18 # Yarn과 호환성이 좋은 LTS 버전

      - name: Install dependencies
        run: yarn install --frozen-lockfile # Yarn을 사용하는 경우 적절한 설치 방식

      - name: Run Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

name: Preview

on:
  pull_request:
    branches: ['main', 'develop']

permissions:
  contents: write

  pages: write

  deployments: write

  id-token: write

  issues: write

  pull-requests: write

jobs:
  storybook-preview:
    runs-on: ubuntu-20.04

    steps:
      - name: 저장소 체크아웃

        uses: actions/checkout@v3

        with:
          fetch-depth: 0

      - name: 캐시 종속성

        id: cache

        uses: actions/cache@v3

        with:
          path: '**/node_modules'

          key: ${{ runner.os }}-node-${{ hashFiles('**/yarn.lock') }}-storybook

      - name: 종속성 설치

        if: steps.cache.outputs.cache-hit != 'true'

        run: yarn install

      - name: Chromatic에 게시

        id: chromatic

        uses: chromaui/action@v1

        with:
          projectToken: ${{ secrets.CHROMATIC_TOKEN }}

          token: ${{ secrets.GITHUB_TOKEN }}

          onlyChanged: true

          autoAcceptChanges: true

      - name: 현재 시간 가져오기

        uses: josStorer/get-current-time@v2

        id: current-time

        with:
          format: 'YYYY년 MM월 DD일 HH시 mm분 ss초'

          utcOffset: '+09:00'

    outputs:
      storybook_url: ${{ steps.chromatic.outputs.storybookUrl }}

      currnent_time: ${{ steps.current-time.outputs.formattedTime }}

  github-bot-storybook:
    runs-on: ubuntu-latest

    needs: [storybook-preview]

    steps:
      - name: PR 코멘트 남기기

        uses: thollander/actions-comment-pull-request@v2

        with:
          comment_tag: ${{github.event.number}}-storybook

          message: |

            Storybook: ${{ needs.storybook-preview.outputs.storybook_url }}

            Update: ${{ needs.storybook-preview.outputs.currnent_time }}

onlyChaged / autoAcceptChanges

두 가지 속성을 true 로 하였다.

onlyChanged: true

autoAcceptChanges: true

onlyChanged

이전에 테스트된 storybook 과 비교하여 변경된 부분만 다시 테스트하여 빌드 시간과 불필요한 리소스 사용을 방지할 수 있다.

autoAcceptChanges

변경 사항을 자동으로 승인하여 작업 흐름을 단순화하였다.

comment_tag

수정사항이 있어 계속 Pull Request 에 push 를 하면 계속 깃허브 봇이 댓글을 남기게 된다. 그러면 가독성도 좋지 않고 불필요한 주소가 여전히 남아있게 된다.

그래서 댓글을 고유하게 식별할 수 있는 comment_tag 를 사용하였다. 그러면 기존 댓글 대체하게 되어 한 개의 댓글에서만 새로운 주소가 계속 업데이트된다.

나는 pr 번호로 댓글을 고유하게 식별하였다.

comment_tag: ${{github.event.number}}-storybook

배포된 시간

comment tag 를 추가했으니깐 해당 댓글에 있는 링크가 언제 업데이트된 것인지 알려주기 위해 현재 시간을 보여주었다.

- name: 현재 시간 가져오기

  uses: josStorer/get-current-time@v2

  id: current-time

  with:

    format: "YYYY년 MM월 DD일 HH시 mm분 ss초"

    utcOffset: "+09:00"

배포링크 제공

추가로 PR 코멘트로 바로 스토리북 배포 링크를 확인할 수 있도록 액션을 추가해주었다.

...

jobs:
  storybook:
    runs-on: ubuntu-20.04
    outputs:
      status: ${{ job.status }}
    steps:
    
     ...
     
      - name: comment PR
        uses: thollander/actions-comment-pull-request@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          message: "🚀storybook: ${{ steps.chromatic.outputs.storybookUrl }}"

배포 테스트

깃허브 커밋하기

위 코드대로 깃허브에 커밋하면 아래와 같이 Github Action에서 배포가 되는걸 볼 수 있다.

또한, PR을 열 경우, 아래와 같이 배포주소와 마지막으로 Update 한 시간이 나온다.

### 회고

장점

배포를 통해 공유하기 쉽다.
- 스토리북을 배포함으로써 다른 개발자, 다른 팀원들과 스토리북 내용을 쉽게 공유할 수 있다.
- 다른 팀원들은 URL만 알면 스토리북의 진행상황을 알 수 있기 때문에 따로 스토리북을 설치해야 한다던가 개발자에게 찾아가야 한다는 귀찮은 일을 없앨 수 있다.
- 또한 Figma 플러그인을 사용하면 Chromatic으로 배포된 스토리북을 Figma에 쉽게 가져올 수 있다는 점
UI Test를 통해서 변경사항을 쉽게 알아볼 수 있다.
- 다른 테스트 툴들이 많이 있지만 스토리북에 대해서 UI 변경사항을 쉽게 볼 수 있다는 점은 장점이라고 생각한다.
- UI 뿐만아니라 코드에서도 변경사항을 알려주고 팀원들과 코드리뷰 처럼 UI 리뷰를 진행하면 개발에 큰 도움이 될 것이라 생각한다.

단점

빌드시간이 너무 오래 걸린다.
- 이건 내가 yml 파일을 잘못 설정했거나 다른 이슈일수도 있지만, 엄청나게 많은 수정사항이 있는 상태에서 3분이상의 시간이 소요되는건 그럴 수 있다고 생각하지만, 버튼 컴포넌트를 하나 만들고 background color 하나 수정하는데 3분 이상이 걸리는건 너무 길다고 생각한다
Accept을 하는 이유?
- github 코드리뷰를 생각해보면 예를 들어 팀원 2명 이상이 Approve를 눌렀을 때 merge가 되는 제한을 설정할 수 있다.
- 약간 그런 기대를 하고 있었는데, CI가 실행되고 merge 가능 상태가 되어버리지만Chromatic에서는 아직 Accept 되지 않은 상태였다.
- 만약 UI 변경사항에 문제가 있는데 누군가 그냥 merge를 눌러버린다면, Chromatic으로 Accept을 할 필요가 없어보인다. (github actions을 추가해서 해결할 수 있는지는 잘 모르겠다.)

울랄라신나

신나는 개발일기

이전 포스트

피그마 스토리북 연동

다음 포스트