NPM에 라이브러리 배포하기: Storybook 자동 배포편

---

0. 배경

NPM에 surff 라이브러리를 배포한 후, 로컬에서 실행을 해 올바르게 컴포넌트가 동작하는지를 보는 것은 라이브러리 사용자에게 불편함을 느끼게 한다는 사실을 깨닫게 되었다. 불편함을 해소하기 위해선 사용자에게 라이브러리의 동작을 보여주고, 제어할 수 있는 도구를 제공해야 했다. 

 

• 모든 컴포넌트와 커스텀 훅을 보여주어야 한다.
• 컴포넌트의 props을 조절할 수 있어야 한다.
• 부수적인 설치 없이 손쉽게 제공되어야 한다. 

위의 조건을 만족하는 방법은 Storybook을 통해 컴포넌트와 훅의 동작을 보여주고, 이를 웹에 게시하여 부수적인 설치 없이 url을 통해 Storybook을 확인할 수 있도록 하는 것이었다.

 

1. Storybook 설치

npx storybook@latest init

 

2. Storybook 제작

(1) 불필요한 파일 삭제

stories/ 내부에 존재하는 모든 파일을 삭제하면 된다.

 

(2) storybook 폴더 이동

기본적으로 storybook을 설치하게 되면, root 하위에 stories/가 존재하게 된다. 현재 라이브러리의 폴더 구조 중 코드와 관련된 부분은 packages/ 하위에 위치해 있기에, stories도 해당 폴더 내부로 이동해 주었다.

packages/
├── stories/
├── components/
├── hooks/
└── index.ts
└── main.tsx
└── vite-env.d.ts

 

(3) .storybook 설정 변경

stories 폴더를 이동한 후, .storybook/ 내부의 main.ts 설정을 변경해주어야 한다. storybook의 경우, .storybook에 있는 내용을 기반으로 동작이 되기 때문이다.

(storybook 폴더를 이동하지 않았다면, 변경하지 않아도 되는 설정이다.)

• config.stories
  • ../stories/**/*.mdx > ../packages/stories/**/*.mdx 로 변경
  • ../stories/**/*.stories > ../packages/stories/**/*.stories 로 변경

import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  stories: [
    "../packages/stories/**/*.mdx",
    "../packages/stories/**/*.stories.@(js|jsx|mjs|ts|tsx)",
  ],
  addons: [
    "@storybook/addon-onboarding",
    "@storybook/addon-essentials",
    "@chromatic-com/storybook",
    "@storybook/addon-interactions",
  ],
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
};
export default config;

 

(4) 컴포넌트의 Storybook 제작

• meta 구현
  • title: Storybook 문서에서 구조 
  • component: 사용하고자 하는 컴포넌트
• Story 구현
  • args: 컴포넌트의 props

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

const meta = {
  title: "components/Skeleton",
  component: Skeleton,
  tags: ["autodocs"],
  parameters: {
    layout: "centered",
  },
} satisfies Meta<typeof Skeleton>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Image: Story = {
  args: {
    width: 60,
    height: 60,
  },
};

export const Text: Story = {
  args: {
    width: 202,
    height: 21,
  },
};

 

3. Storybook 빌드

(1) 명령어 입력

pnpm build-storybook

 

(2) storybook-static 확인

root 하위에 storybook-static 폴더가 생성되는 것을 확인할 수 있다. 이 파일을 활용하여 배포를 할 것이다.

 

4. Storybook 자동 배포

(0) 배포 사이트

Storybook을 배포하는 방법엔 크게 세 가지가 있다.

• Github Pages
• Vercel
• Chromatic

Github Pages와 Vercel의 경우, url로 접속하여 Storybook을 볼 수 있으며, Chromatic의 경우 다른 사용자와 상호작용까지 가능한 서비스이다. 이 중 필자가 선택한 방법은 Github Pages이다.

세 가지 서비스 중 정적 사이트에 Github Pages가 적합하다는 판단을 했다. Vercel과 Chromatic의 경우, 동적 사이트에 적합하며 특히 Chromatic의 경우 제공하는 서비스가 많아서 그런지 접속하는 시간이 오래 걸려 탈락했다.

 

(1) Github Actions 활성화

 

(2) 배포 반영 환경설정

Storybook의 공식 문서를 참고하여, 특정 branch에 코드가 push 되었을 때 자동적으로 Github Pages에 배포되도록 했다. 필자의 경우, release branch에 코드가 push되었을 때 배포되도록 설정했다.

 

surff 라이브러리의 경우, 완성된 기능을 곧바로 main branch에 올리는 것이 아니라 다음과 같이 개발을 진행한다.

• [main branch] 개발을 진행한다.
• [main branch > release branch] 개발을 완성된 후 release branch에 이러한 변경 사항을 반영한다.
• [relase branch] NPM에 버전을 올려 배포한다.

개발 중인 상황에서 Storybook이 해당 변경 사항을 즉시 반영하기보단 특정 기능을 완성한 후 배포했을 때의 변경 사항을 반영하는 것이 올바른 방향이라고 판단을 했다. 그렇기에 release branch로 반영 branch를 설정하게 되었다.

 

(3) workflow 작성

위치: .github/workflows/deploy-github-pages.yml

# Workflow name
name: Build and Publish Storybook to GitHub Pages

on:
  push:
    branches: ["release"]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # Manual Checkout
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # Set up Node
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      #👇 Add Storybook build and deploy to GitHub Pages as a step in the workflow
      - uses: bitovi/github-actions-storybook-to-github-pages@v1.0.3
        with:
          install_command: yarn install
          build_command: yarn build-storybook
          path: storybook-static
          checkout: false

 

(4) workflow 작동

 

(5) 배포된 Github Pages 확인

⚡배포된 주소: https://minjeongss.github.io/surff/

성공적으로 배포된 것을 확인할 수 있다! 😀👍