[Next] Storybook으로 UI 컴포넌트 문서화하기 (1) - 기본 설정

안녕하세요. J4J입니다.

 

이번 포스팅은 storybook으로 UI 컴포넌트 문서화하기 첫 번째인 기본 설정에 대해 적어보는 시간을 가져보려고 합니다.

 

 

 

Storybook이란?

 

storybook은 react, next, vue 등의 FE 개발자들이 많이 사용하는 다양한 기술 스택에서 활용할 수 있는 UI 컴포넌트 문서화 오픈 소스 도구입니다.

 

storybook을 BE 입장에서 가장 대표적으로 비교해 볼 수 있는 것은 swagger가 될 수 있습니다.

 

API 산출물을 swagger를 통해 확인할 수 있는 것처럼 서비스 개발을 위해 만들어진 다양한 컴포넌트 및 페이지들의 산출물을 확인할 수 있도록 도와주는 것이 storybook입니다.

 

 

 

Storybook 공식 문서를 확인해 보면 storybook을 사용했을 때 얻을 수 있는 이점은 다음과 같이 정리하고 있습니다.

 

• 내구성이 높은 UI 개발을 할 수 있음
• 더 적은 노력으로 UI 테스트를 수행할 수 있음
• 재사용이 될 수 있도록 팀원들을 위한 UI 문서화를 제공할 수 있음
• UI의 실질적인 동작을 공유할 수 있음
• UI 워크플로우를 자동화할 수 있음

 

 

 

공식 문서에서 소개하는 이점들은 실제로 storybook을 사용했을 때 대부분 쉽게 경험해 볼 수 있었습니다.

 

팀원들과 협업할 때에도 많은 도움을 받을 수 있었고 심지어 혼자서 개발한다고 하더라도 storybook을 통해 문서화가 제대로 이루어져 있다면 UI의 동작을 이해하는데 도움을 받을 수 있었습니다.

 

그래서 만약 storybook 사용에 대한 고민을 가지고 계신 분들이 있다면 적극적으로 사용하는 것을 권장드립니다.

 

 

반응형

 

 

Storybook 사용 환경 설정

 

storybook에 대해 간단히 설명을 드렸으니 next에서 storybook 사용하는 환경 설정을 해보겠습니다.

 

 

 

[ 1. storybook 초기 구성 ]

 

storybook 초기 구성은 storybook에서 제공해 주는 cli를 이용하여 편리하게 설정해 볼 수 있습니다.

 

cli를 입력하면 사용되는 프로젝트에 맞게 자동으로 사용할 수 있는 환경 구성을 해줍니다.

 

중간마다 발생되는 질문들은 대부분 yes로 해주시면 되지만 읽어보시고 각자의 판단대로 수행해 주시면 됩니다.

 

$ npx storybook@latest init

 

Need to install the following packages:
storybook@7.6.6
Ok to proceed? (y)

 

√ We have detected that you're using ESLint. Storybook provides a plugin that gives the best experience with Storybook and helps follow best practices: https://github.com/storybookjs/eslint-plugin-storybook#readme      

Would you like to install it? ... yes

 

 

 

설치가 올바르게 되었다면 다음과 같은 페이지가 자동으로 오픈되는 것을 볼 수 있습니다.

 

storybook 설치 후 오픈 페이지

 

 

 

 

[ 2. 초기 구성 확인 - 설정 파일 ]

 

설치가 올바르게 되었다면 cli를 통해 생성된 초기 구성을 확인해 보겠습니다.

 

먼저 설정 파일입니다.

 

설정 파일은 총 2가지로 다음과 같이 .storybook 폴더 아래에 main, preview 파일입니다.

 

초기 설정 파일

 

 

 

먼저 main은 storybook의 전체적인 동작 및 기능과 관련된 설정 파일입니다.

 

생성된 파일을 확인해 보면 다음과 같이 구성되어 있는 것을 볼 수 있습니다.

 

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

const config: StorybookConfig = {
    // storybook에 보여질 대상 파일 경로
    stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],

    // storybook에 사용되는 추가 기능 설정
    addons: [
        '@storybook/addon-links', // storybook 내부에서 페이지 이동을 가능하게 하는 link 기능 제공
        '@storybook/addon-essentials', // storybook 초기 사용에 도움이 되는 third-party 기능 제공
        '@storybook/addon-onboarding', // storybook 초기 사용에 도움이 될 수 있는 가이드 기능 제공
        '@storybook/addon-interactions', // storybook에서 렌더링 이후 user interaction이 가능하도록 기능 제공
    ],

    // storybook에서 사용되는 framework 구체화를 위한 설정
    framework: {
        name: '@storybook/nextjs',
        options: {},
    },

    // storybook에 보여지는 파일들 대상으로 자동 문서화 기능 제공 (stories 파일 내부에서 tags: ['autodocs'] 설정 활용)
    docs: {
        autodocs: 'tag',
    },
};
export default config;

 

 

 

다음으로 preview 파일은 storybook에 보이는 각각의 컴포넌트들에 적용해줘야 하는 설정들을 전역적으로 설정하도록 도와줍니다.

 

생성된 파일을 확인해보면 다음과 같이 구성되어 있는 것을 볼 수 있습니다.

 

import type { Preview } from '@storybook/react';

const preview: Preview = {
    parameters: {
        // 발생되는 event handler 이름이 regix에 포함되는 경우 actions에 발생된 event 로그 표시 제공
        // ex) onClick event가 발생되는 경우 onClick event 처리와 관련된 로그 표시를 actions에서 확인 가능
        actions: { argTypesRegex: '^on[A-Z].*' },
        controls: {
            matchers: {
                // props 이름이 regex에 포함되는 경우 color 선택 ui 제공
                // ex) props 이름이 backgroundColor인 경우 color 선택할 수 있는 ui 제공
                color: /(background|color)$/i,
                // props 이름이 regex에 포함되는 경우 date 선택 ui 제공
                // ex) props 이름이 인 경우 startDate인 경우 date 선택할 수 있는 ui 제공
                date: /Date$/i,
            },
        },
    },
};

export default preview;

 

 

 

 

[ 3. 초기 구성 확인 - 샘플 코드 ]

 

다음은 샘플 코드입니다.

 

프로젝트 구조를 확인해보면 /src/stories 경로가 새롭게 생성되어 있는 것을 볼 수 있습니다.

 

해당 경로에 들어 있는 파일들은 storybook에서 제공해 주는 샘플 코드이며 해당 코드를 보면서 어떻게 storybook을 구성하는 파일들을 생성할 수 있는지 참고하시면 됩니다.

 

그리고 이런 파일들이 있었기 때문에 위에서 storybook이 오픈되었을 때 다양한 컴포넌트들을 storybook에서 확인할 수 있었습니다.

 

초기 샘플 코드

 

 

 

 

[ 4. 초기 구성 확인 - package.json script ]

 

다음 구성 확인은 package.json script입니다.

 

package.json을 확인해 보면 다음과 같이 storybook을 위한 script가 자동으로 추가되어 있는 것을 볼 수 있습니다.

 

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

 

 

 

storybook은 local 환경에서 storybook을 실행하기 위한 script로 cli를 통해 초기 구성되었을 때 실행된 명령어와도 같습니다.

 

build-storybook은 현재 구성된 storybook 환경을 이용하여 build를 수행한 것으로 배포 등의 목적으로 build가 필요하실 때 사용해 볼 수 있습니다.

 

참고로 build를 수행하면 storybook-static 경로에 다음과 같이 번들링이 수행된 결과물을 확인할 수 있으며 index.html 파일을 실행해 보면 build 된 결과물을 이용하여 storybook을 확인할 수 있습니다.

 

초기 코드 build 수행

 

 

 

 

 

 

 

 

이상으로 storybook으로 UI 컴포넌트 문서화하기 첫 번째인 기본 설정에 대해 간단하게 알아보는 시간이었습니다.

 

읽어주셔서 감사합니다.