React + Yarn berry 환경에 Storybook 도입하기

🏃‍♀️‍➡️ 개요

이 글에서는 전세대출 서비스 사이드 프로젝트에서 컴포넌트 관리와, 스토리북(Storybook)을 도입한 경험에 대해 공유하려 합니다. 스토리북(Storybook)의 개념과 팀 내에서 어떻게 활용했는지에 대한 방법에 대해 설명합니다.

 

🚨 문제 상황

개발팀에서 작업을 진행할 때, 특히 여러 명이 함께 프로젝트를 진행하는 경우 컴포넌트의 효율적인 관리는 언제나 큰 도전 과제입니다.

이번 전세대출 서비스 사이드 프로젝트에서도 비슷한 문제가 발생했습니다. 금융계산기 페이지개발하면서 총 4가지 계산 기능을 나누어 2개씩 나누어 개발하게 되었습니다. 작업을 진행하다 보니 각 페이지에서 공통으로 사용하는 UI 컴포넌트들이 많았고,UI의 일관성을 유지하면서도 개발 효율성을 높일 방법을 모색했습니다.

이를 해결하기 위해 먼저 공통 컴포넌트를 만드는 작업을 우선적으로 진행하기로 했습니다. 뿐만 아니라, 다른 페이지에서도 밀린 공통 컴포넌트들을 분리하기로 결정하였습니다.

🔮 스토리북을 도입하자

이러한 상황을 해결하기 위해 공통 컴포넌트를 체계적으로 관리하고, 팀원들이 손쉽게 재사용할 수 있는 환경을 구축하는 것이 필요했습니다. 저희 팀에서는 특히 공통 컴포넌트의 시각화를 통해 이해를 도울 필요가 있다고 생각했고, 이에 팀원들과의 논의한 끝에 스토리북(Storybook)의 도입하기로 결정했습니다.

 

🤷‍♀️ 스토리북이란?

스토리북은 독립적으로 UI 컴포넌트를 작성하고 시각적으로 확인할 수 있는 도구입니다. 웹 애플리케이션 개발에서 UI 컴포넌트를 만드는 데 집중할 수 있게 해주며, 컴포넌트 단위로 시각화할 수 있는 환경을 제공합니다. 이를 통해 팀원 간 협업을 원활하게 하고, 재사용 가능한 컴포넌트의 일관성을 유지하는 데 도움이 됩니다.

독립적 컴포넌트 개발

스토리북은 애플리케이션의 전체 구조와 상관없이 개별 컴포넌트를 독립적으로 렌더링하고 테스트할 수 있습니다. 이는 특정 컴포넌트를 쉽게 수정하고 그 결과를 빠르게 확인할 수 있게 해줍니다.

컴포넌트 스토리

각 컴포넌트는 "스토리"라는 형태로 정의됩니다. 스토리는 컴포넌트가 다양한 상태(예: 다른 속성, 이벤트 등)에서 어떻게 보이는지를 나타냅니다. 이를 통해 UI를 실시간으로 시각화하고, 상태나 속성에 따른 컴포넌트의 다양한 변화를 쉽게 확인할 수 있습니다.

문서화 기능

스토리북은 컴포넌트의 상태나 속성, 인터랙션 등을 문서화할 수 있습니다. 이는 프로젝트에 참여하는 개발자나 디자이너가 해당 컴포넌트를 이해하고 재사용하는 데 도움을 줍니다.

👍 스토리북의 장점

컴포넌트 시각화

스토리북을 통해 컴포넌트가 어떻게 렌더링되는지 실시간으로 시각적으로 확인할 수 있습니다. 이를 통해 컴포넌트가 여러 상태에서 어떻게 동작하는지 쉽게 파악할 수 있고, 디자인과 기능이 맞물리는 부분에서 문제를 조기에 발견할 수 있습니다.

협업 효율성 증가

개발자뿐만 아니라 디자이너와 QA 팀도 스토리북을 통해 컴포넌트의 실제 동작을 시각적으로 확인할 수 있습니다. 이를 통해 디자인 피드백이나 기능 확인이 더 쉽고 빠르게 이루어지며, 협업 효율성이 극대화됩니다.

컴포넌트 재사용성 향상

스토리북에 등록된 컴포넌트들은 모두 문서화되기 때문에, 다른 팀원들이 해당 컴포넌트를 쉽게 이해하고 사용할 수 있습니다. 이를 통해 중복 코드 작성을 방지하고, 일관된 컴포넌트 사용을 유도합니다.

디자인 시스템 구축

스토리북은 디자인 시스템을 구축하거나 유지보수하는 데 매우 유용합니다. 컴포넌트를 체계적으로 관리함으로써, 디자인 일관성을 유지할 수 있고, 컴포넌트 수정 시 이를 다른 곳에서도 일관되게 반영할 수 있습니다.

이러한 장점 덕분에 스토리북은 특히 UI가 복잡한 프로젝트나 다수의 팀원이 협업하는 프로젝트에서 큰 효과를 발휘합니다.

 

🦾 Storybook 세팅하기

1. 설치 명령어

Yarn Berry 환경에서 Storybook을 설치하기 위해 yarn dlx를 사용합니다.

yarn dlx storybook@latest init

이 명령어는 Storybook을 설치하고 필요한 기본 설정을 자동으로 수행해 줍니다.

2. .yarnrc.yml 설정 확인

nodeLinker: pnp

Yarn Berry 환경에서는 .yarnrc.yml 파일에서 PnP(Plug'n'Play) 기능을 관리하므로, nodeLinker 설정이 pnp로 되어 있는지 확인하세요.

Storybook은 PnP를 기본적으로 지원하지만, 일부 플러그인이나 애드온에서 문제가 발생할 수 있으니 PnP 호환이 잘 되는지 확인해야 합니다.

3. 스크립트 설정

Storybook을 실행하기 위한 스크립트를 package.json에 추가합니다.

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

이제 npm run storybook 또는 yarn storybook 명령을 통해 Storybook을 실행할 수 있습니다.

4. Storybook 실행

이제 아래 명령어로 Storybook을 실행합니다.

npm run storybook
# or
yarn storybook

Storybook이 로컬 서버에서 실행되며 기본적으로 http://localhost:6006에서 접근할 수 있습니다.

5. 컴포넌트 스토리 파일 생성

src/components/Button.stories.tsx 같은 파일을 만들어서 컴포넌트의 스토리를 작성합니다.

// Button.stories.tsx

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

const meta: Meta<typeof Button> = {
  title: "shared/Button",
  component: Button,
};

export default meta;

export const Basic: StoryObj<typeof Button> = {
  args: { title: "확인" },
  render: (args) => <Button {...args} />,
};

일부 컴포넌트의 props가 컨트롤 패널에 표시되지 않는 경우, stories.tsx 파일에서 args 설정을 통해 해당 컨트롤을 추가하거나 숨길 수 있습니다.

6. 애드온 설치 (Optional)

스토리북의 기능을 확장할 수 있는 애드온을 설치할 수 있습니다. 자주 사용하는 애드온은 아래와 같습니다. 

• Actions: 컴포넌트의 이벤트 로깅을 지원.
• Controls: 컴포넌트의 Props를 UI로 제어할 수 있게 해줌.
• Docs: 자동으로 문서화된 컴포넌트 문서 생성.

yarn add -D @storybook/addon-actions @storybook/addon-controls

그리고 main.js에 애드온을 추가합니다.

module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-actions',
    '@storybook/addon-controls',
    '@storybook/addon-docs',
  ],
};

이제 Storybook을 통해 컴포넌트를 독립적으로 개발하고 문서화할 수 있습니다.

7. 주의 사항

Yarn Berry의 PnP 환경에서 종종 PnP와 호환되지 않는 라이브러리가 발생할 수 있으므로, 그럴 때는 .yarnrc.yml 파일에 nodeLinker: node-modules로 설정하여 일반적인 node_modules 방식으로 전환할 수도 있습니다.

🙌 결과

 

스토리북을 처음 다뤄보기도 하고, 초반에 공통 컴포넌트들을 분리하느라 애먹었지만 분리하고 스토리북까지 구축하니 뿌듯합니다ㅎㅎ

계산기 아키텍처는 아래와 같이 진행했습니다.

CalculatorPage
│
├── DSRCalculator
│     └── index.tsx
│
├── DTICalculator
│     └── index.tsx
│
├── LTVCalculator
│     ├── index.tsx
│
└── RepaymentCalculator
      └── index.tsx
│
└── index.tsx
└── CalculatorPage.module.scss

계산기 페이지를 CalculatePage하나를 두어서, 각 계산기를 컴포넌트별로 관리하도록 했습니다. 각 컴포넌트는 CalculatePage 폴더 하위에서 관리합니다.

 

이를 통해 각 공통 컴포넌트의 동작과 스타일을 직관적으로 확인하고, 다양한 상태에서의 UI동작을 쉽게 파악할 수 있었습니다. 이 과정에서 컴포넌트 간 일관성도 자연스럽게 확보되었습니다.

⭐️ 후기

스토리북 도입은 단순한 UI 관리 도구를 넘어, 프로젝트의 전반적인 효율성과 팀 내 협업을 촉진하는 중요한 도구였습니다. 공통 컴포넌트의 시각화와 체계적인 관리를 통해 개발 생산성과 디자인 일관성을 모두 잡을 수 있었습니다. 앞으로도 더 나은 개발 환경을 고민하고, 적절한 도구를 도입하도록 해야겠습니다.