[FE] Storybook을 활용한 프론트엔드 컴포넌트 개발

안녕하세요. 뉴비 블로거입니다. 오늘의 글은 storybook 입니다.

 

프론트엔드 개발에서 UI 컴포넌트의 재사용성과 테스트 가능성을 극대화하는 방법 중 하나는 Storybook을 사용하는 것입니다. Storybook은 독립적인 환경에서 UI 컴포넌트를 개발, 문서화 및 테스트할 수 있도록 돕는 도구입니다.

이 글에서는 Storybook의 개념, 주요 기능, 설치 및 사용 방법, 그리고 활용 팁에 대해 다뤄보겠습니다.

---

📌 Storybook이란?

Storybook은 UI 컴포넌트를 독립적으로 개발하고 문서화할 수 있도록 지원하는 개발 도구입니다. React, Vue, Angular 등 다양한 프레임워크를 지원하며, 컴포넌트를 개발하면서 실시간으로 확인하고, 변경 사항을 즉시 반영할 수 있습니다.

🎯 Storybook을 사용하면 좋은 점

1. 컴포넌트 중심 개발: 개별 컴포넌트를 독립적으로 개발하고 테스트할 수 있습니다.
2. 빠른 피드백 루프: 코드 변경 사항을 즉시 반영하여 UI를 확인할 수 있습니다.
3. 문서화 자동화: UI 컴포넌트의 사용법과 다양한 상태를 문서화할 수 있습니다.
4. 비개발자와 협업 용이: 디자이너, PM, QA 팀원들도 Storybook에서 UI를 직접 확인하고 피드백할 수 있습니다.
5. UI 테스트 가능: 스냅샷 테스트, 접근성 테스트 등을 통해 UI의 일관성을 유지할 수 있습니다.

---

🚀 Storybook 설치 및 설정

1️⃣ Storybook 설치

Storybook을 프로젝트에 추가하려면, 이미 React 또는 Vue 프로젝트가 존재해야 합니다. 설치는 아래 명령어를 실행하면 됩니다.

npx storybook@latest init

위 명령어를 실행하면 프로젝트에 적합한 설정이 자동으로 적용됩니다. 만약 특정 프레임워크를 명시하고 싶다면 다음과 같이 실행할 수 있습니다.

npx storybook@latest init --builder vite

설치가 완료되면 package.json에 Storybook 관련 스크립트가 추가됩니다.

"scripts": {
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build"
}

2️⃣ Storybook 실행

Storybook을 실행하려면 다음 명령어를 입력합니다.

npm run storybook

이제 브라우저에서 http://localhost:6006 에 접속하면 Storybook UI를 확인할 수 있습니다.

---

📖 Story 작성하기

Storybook에서는 UI 컴포넌트의 다양한 상태를 정의한 파일을 Story라고 부릅니다. Story를 작성하면 여러 가지 UI 변형을 쉽게 확인할 수 있습니다.

✅ 기본적인 Story 작성

예제: Button 컴포넌트에 대한 Story (Button.stories.tsx)

import { Button } from "./Button";
import { Meta, StoryObj } from "@storybook/react";

const meta: Meta<typeof Button> = {
  title: "Components/Button",
  component: Button,
  args: {
    label: "Click me",
    variant: "primary",
  },
};

export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {};
export const Secondary: Story = {
  args: {
    variant: "secondary",
  },
};
export const Disabled: Story = {
  args: {
    disabled: true,
  },
};

---

✅ Story 설명

• title: Storybook에서 컴포넌트가 위치할 카테고리 (Components/Button).
• component: Story가 다룰 컴포넌트 지정.
• args: 기본 props 값 지정 (스토리 내에서 변경 가능).
• export const [StoryName]: Story의 다양한 변형 정의.

위 Story는 Button 컴포넌트의 세 가지 상태 (Primary, Secondary, Disabled)를 시각적으로 확인할 수 있도록 구성됩니다.

---

🔧 Storybook 애드온 활용

Storybook은 기본 기능 외에도 애드온(Addon) 을 활용하여 UI 개발 경험을 향상시킬 수 있습니다.

1️⃣ Controls Addon (Args 조작)

• UI에서 args 값을 실시간으로 변경할 수 있도록 합니다.
• 기본적으로 포함되어 있으며, args를 설정하면 자동으로 적용됩니다.

2️⃣ Actions Addon (이벤트 핸들링)

• 버튼 클릭 등의 이벤트를 UI에서 확인할 수 있습니다.
• onClick 핸들러를 Storybook에서 테스트할 수 있습니다.

export const ClickableButton: Story = {
  args: {
    onClick: () => console.log("Button clicked!"),
  },
};

3️⃣ Docs Addon (자동 문서화)

• 컴포넌트의 Props 및 사용법을 자동 문서화합니다.
• addon-docs를 추가하면 더욱 풍부한 문서를 생성할 수 있습니다.

npm install @storybook/addon-docs

설정 파일(.storybook/main.js)에서 활성화:

module.exports = {
  addons: ["@storybook/addon-docs"],
};

4️⃣ Accessibility Addon (접근성 검사)

• 웹 표준 및 접근성(A11Y) 테스트를 수행할 수 있습니다.

npm install @storybook/addon-a11y

설정 파일(.storybook/main.js)에서 활성화:

module.exports = {
  addons: ["@storybook/addon-a11y"],
};

---

🎯 Storybook 활용 팁

• 디자인 시스템과 함께 사용
  Storybook을 활용하면 팀 내 디자인 시스템을 정립하고, UI 컴포넌트를 일관되게 유지할 수 있습니다.
• 자동화된 테스트 적용
  Storybook에서 UI 스냅샷 테스트 및 비주얼 리그레션 테스트를 적용하여 변경 사항을 효과적으로 관리할 수 있습니다.
• 실제 API와 연결하기
  msw(Mock Service Worker)와 함께 사용하면, Storybook 환경에서도 API 요청을 시뮬레이션할 수 있습니다.

npm install msw --save-dev

 

• Next.js, Tailwind CSS와 함께 사용하기
  Next.js 및 Tailwind와 Storybook을 함께 사용하려면 .storybook/preview.js에서 스타일을 추가해야 합니다.

import "../styles/globals.css";

---

🔚 결론

Storybook은 UI 컴포넌트를 독립적으로 개발하고 문서화하며, 다양한 상태를 테스트하는 강력한 도구입니다. 특히, 디자인 시스템 구축, 협업, 자동화 테스트 등에 큰 도움을 줄 수 있습니다.

👉 여러분의 프로젝트에도 Storybook을 도입하여 효율적인 UI 개발을 경험해보세요! 🚀