[ Storybook for Vite ] React Vite TypeScript 프로젝트에 Storybook 도입하기

어쩌다가 도입하게 되었는지?

최근 AWS 프론트엔드 모임에서 Storybook에 대한 소개 발표를 들었다.

해당 기술을 현재 프로젝트에 도입하게 된다면 매우 실용적으로 활용할 수 있다는 생각이 들어서 대표님께 강력 어필을 하고, 결국 '당장 도입!!' 이라는 결과를 얻을 수 있었다.

 

Storybook 도입 여정

Storybook 설치

공식 문서 

https://storybook.js.org/docs/react/get-started/install

Install Storybook

 

개발 중인 프로젝트에 Storybook을 설치하는 것은 어렵지 않다.

아래는 storybook을 설치하는 명령어이다.

npx storybook@latest init

아래는 storybook을 로컬 서버로 실행할 수 있는 명령어이다.

 

npm run storybook

처음 storybook을 설치하였을 때, 기본적으로 제공해주는 템플릿 컴포넌트들이 화면에 나타나는 것을 확인할 수 있다.

 

 

Storybook Vite builder 설치

하지만 여기서 추가적으로 세팅해주어야 하는 것이 있다.

바로 우리의 프로젝트는 Vite를 사용하고 있다는 것인데, Storybook은 Webpack 기반의 프레임워크이기 때문에 vite builder를 따로 설치해주어야 한다.

 

공식문서

https://storybook.js.org/docs/6.5/react/builders/vite

Vite

 

Storybook Vite builder는 빠른 ESM 번들러인 Vite와 함께 컴포넌트와 stories를 번들링합니다.

•  Vite로 만든 애플리케이션의 경우: Storybook에서 기존 설정을 재사용할 수 있습니다.
• Webpack으로 만든 애플리케이션의 경우: 시작 및 새로고침 시간이 더 빨라지지만, 컴포넌트의 실행 환경이 애플리케이션과 다르다는 단점이 있습니다.

만약 Vite 어플리케이션에 Storybook을 포함하려면 npx storybook@latest init 명령어를 실행하여 빌더를 설치하고 구성할 수 있습니다. 수동으로 선택하고 싶다면 선택할 수도 있습니다.

 

builder를 설치하려면 아래의 명령어를 입력하세요.

npm install @storybook/builder-vite --save-dev
# yarn add --dev @storybook/builder-vite

builder를 포함하려면 .storybook/main.js|ts 파일의 Storybook 구성을 변경하세요.

// .storybook/main.js|ts

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite', // 👈 The builder enabled here.
  },
};

 

설정(Configuration)

기본적으로 Storybook의 Vite builder는 지원되는 프레임워크에 대한 구성 기본값을 포함하며, 기존 구성 파일과 병합됩니다. Vite builder를 사용할 때 최적의 경험을 위해서는 구성을 직접 Vite의 구성 파일(vite.config.js) 내에서 적용하는 것이 좋습니다.

 

Storybook이 로드될 때, 이는 자동으로 구성을 자신의 구성과 병합합니다. 그러나 모든 프로젝트가 동일한 요구 사항을 가지지는 않으며, Storybook에 특별히 생성된 사용자 정의 구성을 제공해야 할 수도 있습니다. 이 경우 구성 파일(.storybook/main.js|ts)을 조정하고 다음과 같이 viteFinal 구성 함수를 추가할 수 있습니다.

// .storybook/main.js|ts

import { mergeConfig } from 'vite';

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite',
  },
  async viteFinal(config) {
    // Merge custom configuration into the default config
    return mergeConfig(config, {
      // Add dependencies to pre-optimization
      optimizeDeps: {
        include: ['storybook-dark-mode'],
      },
    });
  },
};

 

비동기 함수 viteFinal은 기본 builder configuation이 포함된 configuation 개체를 받고 업데이트된 configuation을 반환합니다.

 

환경에 따라 builder의 configuation를 덮어쓸 수도 있습니다. 예를 들어 개발 목적으로 사용할 사용자 정의 configuation과 프로덕션용 다른 configuation을 제공해야 하는 경우 다음과 같이 기본 configuation을 확장할 수 있습니다.

// .storybook/main.js|ts

import { mergeConfig } from 'vite';

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite',
  },
  async viteFinal(config, { configType }) {
    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return mergeConfig(config, {
      // Your environment configuration here
    });
  },
};

 

TypeScript

만약 TypeScript를 사용해 Storybook의 Vite builder를 config 하려면, .storybook/main.js 파일을 .storybook/main.ts 로 변경하고 아래와 같이 조정하면 됩니다.

// .storybook/main.ts

import type { StorybookConfig } from '@storybook/react-vite'; // your framework

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  framework: '@storybook/react-vite',
  async viteFinal(config, options) {
    // Add your configuration here
    return config;
  },
};

export default config;