React 프로젝트에 Storybook 일단 사용해보기! with TS

💡Storybook에 대한 이해와 학습보다 빠른 적용을 목적으로 정리한 글입니다!

☠️ Storybook 학습 중에 작성한 글이므로 내용에 오류가 있을 수 있습니다!

컴포넌트의 props 값을 편하게 수정하면서 어떻게 렌더링 되는지 쉽게 테스트 할 수 있는 스토리북은 써보면 정말 편하고 좋다. 그렇기에 컴포넌트 단위로 개발을 할 수 있고 또 일종의 프로젝트 문서화 작업도 할 수 있다.

그런데 경험상 처음 써보려고 할때 스토리북이 정확히 뭔지도 모르겠고 어떻게 시작해야 할지 감이 잘 안 오는데 무엇보다 스토리 테스트 코드를 따로 작성을 해야 한다는 부담감에 선뜻 시작하기가 어려운 거 같다.

하지만 막상 한번 적용해서 이거저거 건드려보며 어느 정도 적응하고 나면 그냥 공장처럼 찍어낼 수 있다! ^-^)ㅎ

아직 스토리북의 기능을 10%도 제대로 활용 안하고 있는데도 너무 재밌고 편해서 시작하기 막막한 분들에게 도움이 됐으면 해서 지금 당장 깊은 생각이나 고민 없이 바로 적용해 볼 수 있도록 적용 과정을 정리해봤다.

 

1. 설치

npx -p @storybook/cli sb init
npx sb init

위의 명령어 중 하나를 터미널 창에 입력해 설치한다.

설치 소요 시간이 조금 있는데 한번에 설치되는 게 아니라 중간중간 현재 프로젝트의 상황에 따라 응답을 요구하기도 한다.

설치되는걸 잘 보다가 갑자기 멈추면 유심히 로그를 살펴보자!

참고로 스토리북 설치는 CRA나 리액트 프로젝트 세팅을 끝내고 하는 걸 추천한다.

프로젝트 세팅이 끝나있으면 스토리북이 알아서 프로젝트 타입을 탐색하고 그에 맞춰서 설치해준다!

 

💬 설치 중 내가 받았던 질문들

1. 처음 설치 할 패키지 체크 질문

Need to install the following packages:
       sb           // 또는 @storybook/cli
Ok to proceed? (y)  // y 누르면 설치 실행

2. Storybook 프로젝트 타입 물어봄

만약 이 질문을 받았다면 지금 내 경로가 제대로 React 프로젝트 폴더가 맞는지 한번 체크해보자!

 

React 프로젝트 경로에 있으면 맨 처음에 알아서 프로젝트 타입을 탐색하고 react 타입으로 설치를 해준다.

2. exlintPlugin migration

🔎 found a 'eslintPlugin' migration:

We've detected you are not using our eslint-plugin.   
In order to have the best experience with Storybook and follow best practices, we advise you to install eslint-plugin-storybook.  
More info: https://github.com/storybookjs/eslint-plugin-storybook#readme

? Do you want to run the 'eslintPlugin' migration on your project? › (y/N)  // y 누르자

 

🔔 설치 완료

To run your Storybook, type:

   npm run storybook 

For more information visit: https://storybook.js.org

터미널에 위의 로그가 뜨면 설치 완료다!

스토리 북이 설치가 정상적으로 끝나면 설치한 경로에 아래의 파일들이 생성된다!

이게 뭐지 싶은데 별거 없다.

.storybook은 스토리북의 환경 설정 파일이 들어있는 폴더고

stories는 스토리북의 기본 예제 코드들이 들어있는 폴더다.

스토리북이 친절하게 이런 식으로 작성하라고 다 알려준다.

^-^)b 스토리북 최고!

 

어쨌든 중요한건 .storybook이고 stories는 실질적으론 중요하지 않다.

 

따라서 폴더 채로 지워버려도 되....지만!!!

지우기 전에 스토리북이 제대로 설치됐는지 테스트 해보고 지우는걸 추천한다!

 

😋 잘 설치 됐는지 실행해보기!

npm run storybook

아까 전 설치 완료 메세지에서 알려줬던 그 명령어를 터미널에 입력해본다.

 

그러면 스토리북이 뭔가 윙윙하면서 열심히 일을 하다가 

 

 

React 프로젝트 실행했을 때처럼 퐉! 🎉 하고 스토리북이 켜진다.

만약 터미널은 멈췄는데도 창이 안 뜨면 당황하지 말고 터미널을 거슬러 올라가서

Storybook에 할당된 포트 번호를 찾아서 수동으로 localhost:포트번호 주소로 접속하면 된다!

참고로 스토리북을 한번 실행하면 저장할 때마다 React 프로젝트처럼 자동으로 재실행된다.

그래서 이대로 그냥 계속 켜 두는 거 추천!

 

2. 스토리북 초기 설정

🎀 Global Style 과 ThemeProvider 적용

const root = createRoot(document.getElementById('root') as HTMLElement);
root.render(
  <React.StrictMode>
    <ThemeProvider theme={defaultTheme}>
      <GlobalStyle />
      <App />
    </ThemeProvider>
  </React.StrictMode>,
);

 

만약 현 프로젝트에서 GlobalStyle이나 ThemeProvider를 이용해 Default Style을 적용하고 있다면 스토리북에도 적용이 되도록 따로 설정을 하나 해줘야 한다.

어렵고 복잡한 건 없고 그냥 아까 설치됐던 스토리북의 환경 설정 관련 폴더인 .storybook 내의 preview.js 파일로 들어가 ThemProvider, GlobalStyle, Default Style을 import 하고 맨 아래에 이 코드를 복붙 해서 추가해주면 된다.

 

export const decorators = [
  (Story) => (
    <ThemeProvider theme={defaultTheme}>
      <GlobalStyle />
      <Story />
    </ThemeProvider>
  ),
];

이런 식으로 추가하면 된다!!!!

 

decorators는 대충 스토리북에서 렌더링 할 때 컴포넌트의 스타일 외로 추가적인 스타일을 적용할 수 있게 해주는 기능이다.

이걸 preview.js에 적용하면 앞으로 스토리북으로 띄울 모든 컴포넌트들에게 Global decorators를 달아주는 거라고 보면 된다.

조금 더 정확한 내용은 공식 사이트의 Decorators 글을 참고!

 

🧭 절대 경로 설정

언제나 골치 아프게 하는 경로 설정!

스토리북에서도 절대경로를 사용하려면 따로 설정을 해줘야 한다고 한다!

근데 사실 나는 딱히 뭐 설정 안 해줬는데 스토리 코드 내에서 절대 경로를 사용해도 잘 적용이 된다...ㅎ-ㅎ)?

내가 잘못 사용하고 있는 건가 싶긴 한데...

 

그래서 만약 설정해주는 게 귀찮다면 일단 이 설정을 건너뛰고 작업을 먼저 해보다 경로로 문제가 생기면 그때 시도해봐도 좋을 거 같다. 아니면 처음엔 상대 경로로 먼저 해보는 것도 나쁘지 않을 지도...!

 

1. tsconfig에 경로 설정을 한다.

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
    }
  }
}

2. '.storybook' 폴더 내의 main.js 파일에서 설정해준다.

초기 main.js를 보면 이렇게 되어 있는데!

먼저 path 모듈을 import 해주고 core 아래에 이 코드를 추가해주면 된다!

const path = require('path');

...

core: {
    builder: '@storybook/builder-webpack5',
},
/* 요거 추가! */
webpackFinal: async config => {
  config.resolve.modules = [path.resolve(__dirname, '..'), 'node_modules', 'styles'];
  config.resolve.alias = {
    ...config.resolve.alias,
    '@components': path.resolve(__dirname, '../src/components')
  };
  return config;
 },

더 추가하고 싶은 경로가 있다면 config.resolve.alias 아래에 '설정하려는 경로 별칭' : 실제 경로 형태'로 작성하면 된다.

이 방법은 path 모듈을 사용해야 하는데 무슨 TsconfigPathPlugin을 사용해서 적용하는 방법도 있고, 아래와 같이 작성하는 방법도 있다고 하는 거 같다.

  webpackFinal: async (config) => {
    config.resolve.modules = [...(config.resolve.modules || []), path.resolve(__dirname, '../src')];
    return config;
  },

이거 저거 해보고 본인 프로젝트에 맞는 방식을 사용하면 될 거 같다.

 

3. 스토리 테스트 코드 작성

드디어 실전이다!

하지만 TypeScript로 작업을 하고 있다면 크게 걱정할게 딱히 없다!

JavaScript 를 할 때는 모든 컴포넌트들에 일일이 타입을 지정해줘야 제대로 스토리 북을 활용할 수 있는데

이미 TypeScript로 타입을 다 지정해놨으면 그 과정을 건너뛸 수 있어서 아주 좋다!

 

🗂 스토리 테스트 코드 파일 위치

src 아래에만 있으면 딱히 상관없다!

처음 스토리북을 설치했을 때 생겼던 src 폴더 아래의 stories 폴더를 재활용해도 되고 아니면 그냥 작성한 컴포넌트 .tsx 파일과 함께 둬도 된다.

중요한 건 파일의 이름에 .stories 가 들어가느냐다.

여기서 스토리북의 환결 설정 파일 main.js를 다시 살펴보면 아래와 같이 스토리 테스트 코드의 파일 명에 대한 설정도 확인할 수 있다. (물론 원하는대로 수정도 할 수 있다!)

나는 따로 스토리 폴더를 만들어 두지 않고 아래와 같은 구조로 사용하고 있다!

한꺼번에 모아두는 게 관리하기 편한 거 같다 ^-^)b

근데 나중에 스토리 파일들을 다 없애야 하거나 그런 경우가 필요하다면 그냥 한 곳에 모아 관리하는 게 나을 것 같기도 하다!

 

📝 스토리 테스트 코드 작성! with 템플릿 코드

어려울 거 하나 없다!

나는 완전 간단한 템플릿 코드를 만들어두고 이걸 복붙 해서 공장처럼 찍어내고 있다ㅎㅎ!

import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import 컴포넌트 from '컴포넌트.tsx 경로';

export default {
  title: '카테고리이름/컴포넌트이름',
  component: 컴포넌트,
} as ComponentMeta<typeof 컴포넌트>;

const Template: ComponentStory<typeof 컴포넌트> = (args) => <컴포넌트 {...args} />;

export const 커스텀 = Template.bind({});
커스텀.args = {
	값을 지정하고 싶은 속성 : 속성값,
};
커스텀.storyName = '스토리북에 표시할 이름';

export const Default: ComponentStory<typeof 컴포넌트> = (args) => <컴포넌트 {...args} />;

위의 코드에서 한글로 되어 있는 부분을 수정해서 작성하기만 하면 스토리북에 그냥 뜬다! ^-^)b

 

예시를 통해 어떻게 쓰는 건지 좀 더 자세히 알아보면!

예를 들어 위와 같은 props 속성을 가지는 WeekList라는 컴포넌트가 있다고 할 때!

위의 코드를 복붙 해서 한글로 된 부분을 수정을 하고 왼쪽처럼 작성을 하면 오른쪽처럼 뿅! 뜬다.

^-^) ㅎㅎㅎㅎ참 쉽다ㅎㅎㅎㅎㅎ

참고로 스토리북 하단의 Controls에 뜨는 속성들은 전부 weekList.tsx 에서 설정한 weekList 의 props 타입에서 자동으로 가져와진 거다. 만약 이게 TS가 아니고 JavaScript 였다면...propsTypes 로 타입을 다 지정을 해줘야 제대로 뜬다...! ㅠ -ㅠ)!

 

위의 코드에 대해 좀 더 설명을 해보자면

이런 구조라고 보면 된다!

빨간색으로 체크한 title에서 스토리북에 소속될 카테고리를 지정하는데 / 로 구분해서 대분류, 소분류로 나눌 수 있다.

(즉 title에 Calender/ 라고 쓴 모든 컴포넌트들은 제일 큰 카테고리인 Calender에 포함된다!)

 

그리고 그 아래에는 작성한 스토리 코드에 따라 컴포넌트들이 표시가 되는데

맨 아래에 보라색으로 체크한 아무런 속성을 지정하지 않은 스토리가 Default로 추가되고

그 중간에 Template로 생성한 스토리 객체? WeekListEng가 args에 설정한 속성 값이 적용된 상태로,

storyName에 설정한 이름으로 뜬다!

 

필수 코드는 딱 이 부분이고 

import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import WeekList from 'components/calender/components/WeekList';
import weekData from 'components/calender/constants/weekData';

export default {
  title: 'Calender/WeekList',
  component: WeekList,
} as ComponentMeta<typeof WeekList>;

export const Default: ComponentStory<typeof WeekList> = (args) => <WeekList {...args} />;

 

여기서 또 다른 스토리를 추가하고 싶으면 위의 WeekListEng를 복사해서 Template로 스토리 객체들을 생성해서 추가해주면 된다! 아래처럼!

const Template: ComponentStory<typeof WeekList> = (args) => <WeekList {...args} />;

export const WeekListEng = Template.bind({});
WeekListEng.args = {
  data: weekData.eng,
};
WeekListEng.storyName = 'WeekList(Eng)';

/* 스토리 새로 추가 */
export const WeekListJp = Template.bind({});
WeekListJp.args = {
  data: weekData.jp,
};
WeekListJp.storyName = 'WeekList(Jp)';

 

와아아앙!! 추가됐다!!! ^3^)!!!!

 

나는 현재 코드스쿼드에서 진행 중인 3주 미션에서 이 정도까지만 해서 스토리북을 활용하고 있다.

 

스토리북에 대해서 좀 더 찾아보면 스토리북에 뜨는 Controls 들의 타입을 편한 걸로 바꿀 수도 있고

decorators 속성을 사용해 스토리북 내에서 컴포넌트를 좀 더 보기 쉽게 커스텀 할 수도 있다.

일종의 익스텐션인 addon을 추가해 소스 코드도 같이 띄우거나, Readme를 추가해주거나 등 멋지게 쓸 수 있긴 하지만...!

미션 하기도 바쁘고 아직 미션 프로젝트의 규모가 크지 않아서 이 이상의 기능을 추가할 필요까지는 없을 거 같다.

 

이 정도만 해도 좋은 게 속성값을 스토리북에서 이거저거 수정해가며 실제로 잘 적용이 되는지 테스트 하는건 물론이고

컴포넌트를 맨 처음 만들고 나서 스타일이 제대로 됐는지 확인하기 위해 App 파일에 추가하거나 따로 템플릿 페이지를 만들어서 실행해보거나 할 필요 없이 바로바로 저장하고 확인하고 저장하고 확인하고 할 수 있어서 편하다!

그리고 만약 속성 값이 많고, 그 속성에 따라 컴포넌트의 디자인이 휙휙 바뀌어야 하는 경우

해당 디자인을 만들라면 정확히 어떤 속성이 어떤 값이어야 하는지를 스토리북을 보고 빠르게 파악할 수 있어서 너무 편하다!

 

무엇보다 제일 최고라 생각하는 장점은...!

 

✧*.◟( ˊ ᗨ ˋ )◞.*✧

다 만들고 보면 넘 뿌듯함!!!

 

거기다 이렇게 만든 스토리북을 배포도 할 수 있다!!!!!

배포에 대한 내용은...!

따로 글을 파는 게 낫겠다ㅎㅎ!  -> 따로 팠다! 

아무튼 스토리북 너무 좋당!!!! ^0^)!ㅎㅎㅎㅎㅎ

다들 츄라이!!!

 

---

💖 참고

• 스토리북 공식 Tutorials

Storybook Tutorials

• React 를 위한 Storybook 튜토리얼

React를 위한 Storybook 튜토리얼