Storybook과 Chromatic 배포

어진·2026년 1월 2일
chromaticfrontendstorybook

WEB

목록 보기
6/6
post-thumbnail

💡 Storybook이란?

스토리북(Storybook)은 UI 컴포넌트를 독립적으로 개발하고 테스트할 수 있게 해주는 오픈 소스 도구입니다. UI 컴포넌트 라이브러리를 문서화(documentation)하기 위해 사용할 수 있고, 디자인 시스템(Design system)을 구축할 수도 있습니다.

스토리(Story) = 스토리북의 기본 구성 단위
👉🏻 하나의 UI 컴포넌트는 보통 하나 이상의 Story를 가지게 됩니다.
👉🏻 Story는 각 UI 컴포넌트의 다양한 상태와 변형을 시각적으로 보여주는 예시!

스토리북을 사용하면 UI 컴포넌트가 각각 독립적으로 어떻게 실제로 랜더링되는지 직접 시각적으로 테스트하면서 개발을 진행할 수 있습니다. 해당 UI 라이브러리를 사용하는 개발자 입장에서도 코드를 보지 않고도 미리 각 UI 컴포넌트를 체험해보고 사용할 수 있어서 매우 유용합니다.

또한 Storybook에서 제공하는 애드온(Addon) 플러그인을 활용하면 기본적인 기능 이외에도 여러 테스팅 등을 해볼 수 있고, Mockup 상태를 넣어줄 수 있어 상태 값에 따라 변경되는 디자인을 바로 확인할 수 있습니다.

 

💁🏻‍♀️ 그래서 왜 스토리북을 사용할까

  1. 컴포넌트 중심 개발 🌟🌟
    스토리북을 사용하면 UI를 페이지 단위가 아닌 컴포넌트 단위로 독립적으로 개발할 수 있습니다.
    컴포넌트를 분리된 환경에서 테스트하고 관리할 수 있어 재사용성과 유지 보수성이 향상되고, 페이지 의존으로 인한 복잡성도 줄일 수 있습니다.

  2. UI 테스트
    props에 따라 동적으로 반응하는 UI를 다양하게 테스트해 볼 수 있습니다.
    ex) hover/pressed 여부에 따라 다르게 나타나는 컴포넌트, 로딩 중일 때 나타나는 컴포넌트 등
    애드온을 활용하면 스냅샷 테스트, 접근성 테스트 등을 통해 UI의 일관성을 유지할 수 있습니다.

  3. 자동 문서화
    스토리북은 컴포넌트의 사용 예시와 다양한 상태를 문서화하여, 자신이 짠 코드가 아니더라도 컴포넌트의 사용 방법과 옵션, 상태 변화를 쉽게 이해할 수 있도록 돕습니다.

  4. 빠른 피드백 루프
    코드 변경 사항을 즉시 반영하여 UI를 확인할 수 있습니다. 그리고 UI 변경 사항을 팀원들에게 자동으로 배포하여, 리뷰와 승인을 받을 수 있게 합니다. 변경 사항이 approve 되기 전까지는 병합되지 않도록 워크플로를 설정할 수 있습니다.

  5. 디자이너와의 협업 용이
    다른 사람의 코드를 이해하는 데 드는 수고를 줄일 수 있어 개발자 간의 협업이 용이해질 뿐 아니라, 디자이너와의 커뮤니케이션도 효율적으로 만들어줍니다.
    Chromatic으로 Storybook을 배포해 디자이너와 공유하면, 디자이너는 컴포넌트가 디자인 의도에 맞게 구현되고 있는지를 직접 확인할 수 있고 개발자에게 즉각적으로 적절한 피드백을 전달할 수 있습니다.
    이를 통해, 디자인 시스템을 구축하고 공유하며 디자인-개발 간의 불일치를 줄일 수 있습니다!

 

🧩 Chromatic

Chromatic이란?

Chromatic(크로마틱)은 UI 컴포넌트 라이브러리의 시각적 테스트와 리뷰를 자동화하는 도구입니다. 이는 스토리북과 밀접하게 통합되어 있으며, UI 컴포넌트의 변경 사항을 시각적으로 추적하고 팀원들이 리뷰할 수 있도록 도와줍니다. 또한 크로마틱은 CI/CD 파이프라인에 통합하여 UI 테스트의 효율성을 크게 향상시킵니다.

📍 크로마틱의 주요 기능

  • 스토리북 배포
  • 비주얼 리그레션 테스트
  • 자동화된 UI 리뷰

Storybook 배포

크로마틱(Chromatic) = 스토리북 관리자가 만든 무료 배포 서비스

크로마틱을 사용해 스토리북을 온라인으로 배포해 공유할 수 있습니다. 이는 프로젝트의 모든 팀원들이 언제든지 최신 버전의 스토리북을 온라인 상에서 확인할 수 있게 해줍니다. 배포된 스토리북은 버전별로 관리되어, 특정 시점의 UI 상태를 쉽게 확인할 수 있습니다.

💁🏻‍♀️ 그래서 왜 크로마틱을 사용할까

  1. Storybook과의 높은 호환성!
    Storybook 팀이 만든 서비스이기에 Storybook의 구조와 워크플로우를 전제로 설계되어 있습니다.
  2. 배포뿐만 아니라 다양한 UI 변경 관리까지 가능합니다.
  3. Github Actions와 연동해 배포를 자동화할 수 있으며, PR 단위로 UI 변경 사항을 공유하고 리뷰하기에 적합합니다.

 

🚀 사용 예제

Storybook 설정

1️⃣ Storybook 설치

pnpm create storybook@latest

설치가 완료되면 root 폴더에 다음과 같은 구조가 생성됩니다.

  • .storybook/
    - main.ts : Storybook을 위한 config 설정 (addon 포함)
    - preview.ts : 모든 story에 적용될 포맷 설정 파일 (전역 decorator, parameters 설정 등)
  • src/stories/
    - Storybook 예제 컴포넌트들 (*.stories.tsx)

이후 실제 프로젝트에서는 src/stories 대신 각 컴포넌트 폴더에 *.stories.tsx를 두는 방식을 많이 사용합니다.

2️⃣ Story 작성

스토리 파일은
<컴포넌트명>.stories.ts (.tsx | .js | .jsx)형식으로 작성하며,
각 Story는 컴포넌트의 특정 상태(UI state)나 사용 시나리오를 나타냅니다.

export default {
  title: //스토리북에 올릴 컴포넌트 폴더 계층 구조,
  component: // 스토리로 관리할 컴포넌트명
}

export const 스토리명 = () => 해당 스토리에서 테스트할 인자가 담긴 컴포넌트

아래는 버튼 컴포넌트에 대한 기본적인 Story 예시입니다.

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { fn } from 'storybook/test';
import { Button } from './Button';

const meta = {
  title: 'Example/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  args: { onClick: fn() },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    label: 'Button',
  },
};

export const Large: Story = {
  args: {
    size: 'large',
    label: 'Button',
  },
};

export const Small: Story = {
  args: {
    size: 'small',
    label: 'Button',
  },
};

Story의 주요 속성

  • title : 스토리북 폴더 계층 구조
  • component : 스토리로 관리할 UI 컴포넌트
  • args : story의 기본 props
  • decorators : story를 래핑하는 추가 렌더링 기능
  • parameters : story에 대한 정적 메타 데이터 정의 (주로 feature와 addon 조작)

3️⃣ Storybook 실행

pnpm storybook

위 명령어를 실행하면 기본적으로 로컬 환경에서 Storybook이 실행되며, 작성한 컴포넌트의 Story를 바로 확인할 수 있습니다.


(위에서 작성한 Button 컴포넌트의 스토리북 예시 화면)

 

Chromatic으로 배포

로컬 환경에서 Storybook을 확인했다면, 이제 이를 팀원이나 디자이너와 공유 가능한 형태로 배포할 차례인데요
이때 활용할 수 있는 도구가 Chromatic입니다.

1️⃣ Chromatic 프로젝트 선택 및 토큰 발급
1. https://www.chromatic.com 접속
2. GitHub 계정으로 로그인
3. Storybook을 배포할 Repository 선택
4. 생성된 고유한 project-token 복사
이 토큰은 Chromatic이 어떤 프로젝트의 Storybook인지 식별하는 데 사용됩니다.

Chromatic 사이트에 들어가서 GitHub 계정으로 로그인하고 연결할 repository를 설정합니다.
Storybook을 선택하고 프로젝트를 위해 생성된 고유한 project-token을 복사합니다.

2️⃣ Chromatic 설치

pnpm add --save-dev chromatic

3️⃣ Storybook을 Chromatic에 배포

pnpm dlx chromatic --project-token='복사한 프로젝트 토큰'

배포가 완료되면 공유 가능한 Storybook URL이 생성됩니다.
여기까지만 하면 Story를 하나 추가할 때마다 다시 빌드하고 배포해 줘야 합니다.

🛠️ 추가 설정

  • Storybook CI/CD 설정하기
    *.stories.tsx 파일을 변경한 PR을 작성할 때마다 UI 변경 사항을 즉시 확인하고 싶다면, github actions 설정을 통해 자동으로 빌드, 배포되도록 할 수 있습니다.
    참고 🔗 https://www.chromatic.com/docs/ci/

  • Chromatic token을 env로 관리하기
    chromatic 배포 명령어를 실행하면 chromatic에서 자동으로 package.json에 script를 추가해주는데 token이 노출되므로 token을 .env로 관리하는 것이 좋습니다.

지금은 맛보기,, 정도라 실제로 우리 팀 프로젝트에 적용해 보면서 추가하도록 하겠습니다 ㅎㅎ

profile
어진
👩🏻‍💻
이전 포스트

Tailwind CSS와 Shadcn/ui

0개의 댓글