Storybook 기초부터 심화까지 완벽 가이드

Storybook을 활용하여 UI 컴포넌트를 독립적으로 개발하고 문서화하는 방법을 배웁니다. 기본 설정부터 고급 기능까지 실전 예제로 학습합니다.

---

---

들어가며

이 글에서는 Storybook 기초부터 심화까지 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Storybook_기본_설정
2. 첫_번째_Story_작성
3. Args와_Controls_활용
4. Decorators로_공통_레이아웃_적용
5. Parameters로_메타데이터_설정
6. Actions로_이벤트_로깅
7. Play_함수로_인터랙션_테스트
8. MDX로_커스텀_문서_작성
9. Viewport_애드온으로_반응형_테스트
10. Chromatic으로_비주얼_리그레션_테스트
11. Composition으로_멀티_프로젝트_통합
12. Test_Runner로_자동화된_테스트

---

1. Storybook_기본_설정

개요

Storybook을 React 프로젝트에 설치하고 기본 설정을 완료합니다. npx 명령어로 자동 설정이 가능합니다.

코드 예제

# Storybook 설치
npx storybook@latest init

# 개발 서버 실행
npm run storybook

설명

storybook init 명령어가 자동으로 필요한 패키지를 설치하고 설정 파일을 생성합니다. 실행하면 localhost:6006에서 확인할 수 있습니다.

---

2. 첫_번째_Story_작성

개요

간단한 Button 컴포넌트의 Story를 작성합니다. Story는 컴포넌트의 다양한 상태를 보여주는 예제입니다.

코드 예제

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

const meta: Meta<typeof Button> = {
  component: Button,
  title: 'Components/Button',
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { label: '클릭', variant: 'primary' }
};

설명

Meta 타입으로 컴포넌트 메타데이터를 정의하고, StoryObj로 각 상태를 표현합니다. args를 통해 props를 전달합니다.

---

3. Args와_Controls_활용

개요

Args를 사용하여 Storybook UI에서 실시간으로 props를 변경할 수 있습니다. Controls 패널에서 값을 조작할 수 있습니다.

코드 예제

// Button.stories.tsx
export const Primary: Story = {
  args: {
    label: '버튼',
    variant: 'primary',
    size: 'medium',
    disabled: false,
  },
};

export const Disabled: Story = {
  args: { ...Primary.args, disabled: true }
};

설명

args로 정의된 props는 Controls 패널에서 실시간 수정이 가능하며, 다른 Story에서 재사용할 수 있습니다.

---

4. Decorators로_공통_레이아웃_적용

개요

Decorator를 사용하여 모든 Story에 공통 레이아웃이나 Provider를 적용합니다. 전역 또는 개별 Story에 적용 가능합니다.

코드 예제

// Button.stories.tsx
const meta: Meta<typeof Button> = {
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ margin: '3rem' }}>
        <Story />
      </div>
    ),
  ],
};

설명

decorators 배열에 래퍼 컴포넌트를 정의하면 모든 Story에 자동으로 적용됩니다. ThemeProvider나 Router도 이 방식으로 적용합니다.

---

5. Parameters로_메타데이터_설정

개요

Parameters를 사용하여 Story의 동작을 제어하고 추가 정보를 제공합니다. 배경색, 레이아웃, 문서화 옵션 등을 설정할 수 있습니다.

코드 예제

export const DarkBackground: Story = {
  args: { label: '다크 모드 버튼' },
  parameters: {
    backgrounds: {
      default: 'dark',
    },
    layout: 'centered',
  },
};

설명

parameters.backgrounds로 배경색을 변경하고, layout으로 컴포넌트 배치를 조정합니다. 다크 모드 테스트에 유용합니다.

---

6. Actions로_이벤트_로깅

개요

Actions 애드온을 사용하여 컴포넌트의 이벤트 핸들러를 자동으로 로깅합니다. 사용자 상호작용을 추적할 수 있습니다.

코드 예제

// Button.stories.tsx
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    onClick: { action: 'clicked' },
    onHover: { action: 'hovered' },
  },
};

설명

argTypes에 action을 정의하면 이벤트 발생 시 Actions 패널에 자동으로 로그가 표시됩니다.

---

7. Play_함수로_인터랙션_테스트

개요

Play 함수를 사용하여 Story가 렌더링된 후 자동으로 실행될 상호작용을 정의합니다. 자동화된 테스트가 가능합니다.

코드 예제

import { userEvent, within } from '@storybook/test';

export const ClickTest: Story = {
  args: { label: '클릭 테스트' },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
    await userEvent.click(button);
  },
};

설명

play 함수 내에서 userEvent로 클릭, 입력 등의 동작을 시뮬레이션하고 결과를 확인할 수 있습니다.

---

8. MDX로_커스텀_문서_작성

개요

MDX 파일을 사용하여 컴포넌트 문서를 자유롭게 커스터마이징합니다. 마크다운과 React 컴포넌트를 함께 사용할 수 있습니다.

코드 예제

{/* Button.stories.mdx */}
import { Meta, Canvas, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button 컴포넌트

<Canvas of={ButtonStories.Primary} />

## 사용 예시
버튼은 다양한 크기와 스타일을 지원합니다.

설명

MDX를 사용하면 코드 예제, 설명, 디자인 가이드라인을 하나의 문서로 통합할 수 있습니다.

---

9. Viewport_애드온으로_반응형_테스트

개요

Viewport 애드온을 사용하여 다양한 화면 크기에서 컴포넌트를 테스트합니다. 모바일, 태블릿, 데스크톱 뷰를 확인할 수 있습니다.

코드 예제

// .storybook/preview.ts
export const parameters = {
  viewport: {
    viewports: {
      mobile: { name: 'Mobile', styles: { width: '375px', height: '667px' }},
      tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' }},
    },
  },
};

설명

커스텀 뷰포트를 정의하고 툴바에서 선택하여 반응형 디자인을 검증할 수 있습니다.

---

10. Chromatic으로_비주얼_리그레션_테스트

개요

Chromatic을 연동하여 UI 변경사항을 자동으로 감지하고 리뷰합니다. CI/CD 파이프라인에 통합 가능합니다.

코드 예제

# Chromatic 설치 및 배포
npm install --save-dev chromatic

# 프로젝트 토큰으로 배포
npx chromatic --project-token=<your-token>

설명

Chromatic이 모든 Story의 스냅샷을 생성하고, 변경사항이 있으면 리뷰를 요청합니다. 시각적 버그를 사전에 방지할 수 있습니다.

---

11. Composition으로_멀티_프로젝트_통합

개요

Storybook Composition을 사용하여 여러 프로젝트의 Storybook을 하나의 인터페이스에서 관리합니다. 모노레포나 마이크로 프론트엔드에 유용합니다.

코드 예제

// .storybook/main.ts
export default {
  refs: {
    'design-system': {
      title: 'Design System',
      url: 'https://design-system.example.com/storybook',
    },
  },
};

설명

refs 설정으로 외부 Storybook을 연결하면 네비게이션에서 모든 컴포넌트를 한 곳에서 탐색할 수 있습니다.

---

12. Test_Runner로_자동화된_테스트

개요

Storybook Test Runner를 사용하여 모든 Story를 자동으로 테스트합니다. Play 함수와 접근성 테스트를 CI에서 실행할 수 있습니다.

코드 예제

# Test Runner 설치
npm install --save-dev @storybook/test-runner

# 모든 Story 테스트 실행
npm run test-storybook

# package.json
"test-storybook": "test-storybook"

설명

Playwright 기반으로 모든 Story를 실행하고, play 함수의 assertion과 a11y 테스트를 자동으로 수행합니다.

---

마치며

이번 글에서는 Storybook 기초부터 심화까지 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#Storybook #Components #UITesting #Documentation #DesignSystem