Storybook 설치 및 세팅 방법

< 목차 >

1) Storybook 사용 이유

2) Storybook 설치

3) Storybook 세팅

4) Storybook 실행

 

 

 

Storybook

: UI 컴포넌트를 독립적으로 개발, 테스트, 문서화하는 도구

 

주로 디자인 시스템을 구축하거나 공용 컴포넌트를 여러 프로젝트에서 재사용하려고 할 때 사용한다.

 

상태가 복잡한 컴포넌트(UI 상태, 에러 상태 등)를 개발할 때, 디자이너와의 협업 과정에서 컴포넌트를 자주 공유해야 할 때 유용하다.

 

효율적인 개발 환경을 만들고, 디자인 시스템 구축 과정에서의 혼란을 줄일 수 있다.

읽어보면 좋을 자료(https://fe-developers.kakaoent.com/2022/220609-storybookwise-component-refactoring)

 

 

1) Storybook 사용 이유

1. 컴포넌트 개발 환경을 초기부터 체계화

: 초기부터 Storybook을 활용하면 컴포넌트의 UI와 로직을 분리하여 개발할 수 있음

 

2. 컴포넌트 개발의 독립성

- Storybook은 특정 페이지나 앱의 의존성 없이 컴포넌트를 독립적으로 개발하고 테스트할 수 있는 환경 제공

- 페이지 전체를 띄우지 않고 버튼, 입력 필드 같은 단일 컴포넌트를 바로 확인 가능

 

3. 디자인과 개발의 일치성 확인

- 디자이너와 협업 시, Figma와 같은 도구에서 제공된 디자인이 실제 컴포넌트와 얼마나 일치하는지 쉽게 확인 가능

- 각 상태(hover, focus, error 등)를 시각적으로 비교

 

4. 컴포넌트 문서화

- Storybook은 컴포넌트의 사용 방법과 속성을 시각적으로 문서화

- 코드와 함께 사용 사례를 명확히 보여주어 다른 개발자들이 컴포넌트를 쉽게 이해하고 재사용 가능

 

5. 모든 상태를 테스트 가능

- 다양한 상황(예: 버튼의 활성화 상태, 입력 필드의 에러 상태)을 가상의 데이터로 쉽게 테스트

- 예: <Button> 컴포넌트에 여러 속성을 넣어 다양한 UI를 확인 가능

 

6. 협업 효율성 증대

- 디자이너, QA, PM이 Storybook을 통해 컴포넌트를 쉽게 확인하고 피드백 제공

- 개발 완료 전에 디자인 검토를 받아 수정 가능

 

7. 컴포넌트 상태 자동화

- 다양한 속성과 조합을 설정한 스토리를 자동으로 생성해 시각적으로 표시

- 예: Primary Button, Disabled Button 등 상태별 버튼 자동 생성

 

8. 테스팅 도구와 통합

: Jest, Cypress, Chromatic 등과 통합해 시각적 리그레션 테스트나 스냅샷 테스트 가능

 

9. 컴포넌트 재사용성 극대화

: Storybook에서 컴포넌트를 관리하면 재사용 가능한 디자인 시스템을 구성하기 쉬워짐

 

하지만 많은 것을 고려하면서 개발을 하다보니 개발의 속도도 느려지고, 스토리북이라는 새로운 툴을 도입함으로써 세팅과 이슈를 해결하는 데 시간을 더 투자하게 된다는 단점도 있다.

 

 

2) Storybook 설치

: Storybook CLI 설치 및 초기화

 

npx storybook@latest init

 

- 실행하면 Storybook이 현재 프로젝트에 맞게 설정 파일 생성

- Next.js와 TypeScript 환경을 자동으로 감지하여 필요한 설정을 적용

 

 

3) Storybook 세팅

1. Storybook 폴더 구조

: Storybook 초기화 후, 다음과 같은 파일이 생성됨

 

.storybook/
  ├── main.ts
  ├── preview.ts
  └── manager.ts (선택적)

 

- main.js: Storybook 설정 및 애드온 추가

- preview.js: 글로벌 스타일 및 context 설정

- manager.js: Storybook UI 커스터마이징 (선택적)

 

 

2. Next.js와 TypeScript 맞춤 설정

: .storybook/main.ts 파일을 열고 설정 추가

 

import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-onboarding',
    '@storybook/addon-essentials',
    '@chromatic-com/storybook',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
  staticDirs: ['../public'],
};

export default config;

 

 

3. TypeScript 설정

: tsconfig.json에 Storybook 타입 지원 추가

 

{
  "compilerOptions": {
    "types": ["@storybook/react"]
  }
}

 

 

4) Storybook 실행

: 기본적으로 http://localhost:6006에서 Storybook이 실행됨

 

pnpm storybook