Storybook CRA에 적용하기

이번 글은 Storybook의 튜토리얼을 따라해보면서 얻은 지식을 정리하는 글입니다.

Storybook

스토리북은 Component Driven Development를 가능하게 해주는 개발 도구입니다.

스토리북의 기본 단위는 Story로 각 컴포넌트가 렌더링된 상태(버튼이 클릭되었을 경우, 로그인이 되었을 경우)를 캡처한 것입니다.

스토리북은 UI 컴포넌트들이 실제 렌더링되는 Story를 각각 정의하여 스냅샷을 통해 테스트를 진행하면서 개발을 할 수 있습니다. 또한, 사용자와의 상호작용하는 과정을 시뮬레이션하여 UI에 대한 테스트를 진행하거나 배포된 스토리북 사이트에서 인수를 바꿔보면서 실제 렌더링된 컴포넌트에 테스트해볼 수 있습니다.

 

이외에 Storybook의 장점은 Storybook Docs에서 확인할 수 있습니다.

 

 

환경

이번 프로젝트는 간단한 Storybook의 실습을 위한 프로젝트로 CRA환경에서 진행해보도록 하겠습니다.

npx create-react-app . --template typescript

설치

@storybook/cli를 이용해 설치합니다.(@storybook/cli는 Storybook을 빌드하고 개발하는 메인 툴입니다.)

명령어

npx @storybook/cli init

스토리북은 설치 과정에서 프로젝트의 dependency를 확인하고 최적의 설정을 제공해줍니다.

하지만, 설치 과정에서 문제가 생길 경우 —type으로 어떤 환경인지 직접 알려줄 수도 있다. (—type react-> 프로젝트가 react 환경임을 알려줌)

 

해당 명령어를 입력할 경우 storybook관련 addon, dependency를 설치되고 .storybook 디렉토리에 storybook 관련 설정이 작성됩니다. 또한, src/story 디렉토리에 버튼, 헤더, 페이지 관련 story 예시들이 생성됩니다.

(이 후 컴포넌트를 작성할 경우 컴포넌트에 대한 story 파일은 해당 컴포넌트 디렉토리에 함께 생성할 예정이므로 story 디렉토리는 지워도될 것 같습니다. 하지만, 실습에서 활용하기 위해 우선 저는 지우지 않았습니다.)

storybook 설치 직 후 디렉토리

실행

npm run storybook을 입력할 경우 storybook을 로컬 실행하게 되고, 예시 스토리들을 확인해볼 수 있습니다.

예제 story들

여기서 아래 메뉴들 중에 Controls, Actions와 Interacions탭이 있는데 이 기능들은 Storybook에서 추가해준 addons입니다. 이 addons들은 storybook을 설치할 경우 자동적으로 설치된 것들입니다.

각각은 다음의 일을 해줍니다.

• Contorls : 컴포넌트의 인자를 동적으로 바꿀 수 있도록 해줍니다. 원하는 인자들을 테스트하기 위해 코드와 storybook을 왔다갔다 하는 것이 아니라 storybook내에서도 동적으로 인자를 바꿔볼 수 있는 기능을 제공해줍니다.
• Actions : 사용자 상호작용에 의한 콜백이 제대로 작동하는지 확인하는데 도움을 줍니다. 예를 들어, 버튼에 따라 색이 바뀌는 컴포넌트가 있을 경우, 사용자가 버튼을 클릭할 때마다 다른 컴포넌트의 색이 제대로 변경되는지 확인할 수 있습니다.
• Interactions : 디버깅을 위한 유용한 UI를 제공해줍니다. 이는 나중에 나오는 play 기능을 사용할 때 자세히 살펴보도록 하겠습니다.

 

배포

현재 로컬에서 실행중인 storybook을 배포해보도록 하겠습니다.

스토리북 관리자가 만든 무료 배포 서비스인 Chromatic을 사용하겠습니다. Chromatic으로 클라우드에서 스토리북을 안전하게 배포하고 호스팅할 수 있습니다.

 

현재 Storybook 설치가 완료된 CRA프로젝트를 깃허브에 푸시해줍니다.

git remote add origin <github 저장소 주소>

git push -u origin master

 

다음 크로마틱 페이지에 접속하여 로그인해준 뒤, 방금 만든 레포지토리를 연결시켜줍니다.

그 다음 크로마틱 페이지에 나온 순서대로 명령어를 실행합니다.

#npm
npm install --save-dev chromatic
#yarn
yarn add -D chromatic


npx chromatic --project-token={프로젝트 토큰}

해당 명령어를 모두 실행하면 배포가 완료됩니다.

배포 시, scripts에 무언가 추가하겠냐는 질문이 나오는데 이것은 방금 실행한 명령문에 대한 스크립트를 직접 추가해준다는 것으로, project-token이 package.json에서 노출될 수 있으므로 혹시 모를 보안을 위해 저는 삭제했습니다...

package.json에 "readme"가 없다는 오류가 생기는데 해당 오류는 그냥 README파일을 못찾는 다는 것 같아서 REAMD.md를 가리키도록 해주었습니다.

build-storybook.log라는 파일 또한 생기는데 그냥 로그를 작성해주는 것 같아서 .gitignore에 추가해주었습니다.

배포된 이후 chromatic사이트의 프로젝트 화면

그리고 해당 프로젝트에 대한 배포된 storybook을 살펴보기 위해 상세 프로젝트 페이지로 넘어가고 싶었는데, 현재 찾은 방법은 위 사진이 보이는 화면의 제일 아래 쪽에 "Already know how Chromatic works? Go to your project"라는 문구가 있는데 이 문구를 눌러 프로젝트 상세 페이지로 이동하는 방법 밖에 찾지 못했습니다...

프로젝트 상세 페이지

프로젝트 상세 페이지로 이동하면 작성된 story에 대한 Test, 배포된 Storybook 이전 커밋과 달라진 점들을 확인해볼 수 있습니다.

 

CI 구성

프로젝트가 수정될 때마다 배포 명령어를 터미널에 입력하고 수동으로 배포시키는 것은 귀찮을 것입니다. 

그러므로 깃허브 액션을 도입하여 직접 명령어를 치지 않고 자동으로 배포될 수 있도록 해주겠습니다.

 

프로젝트에 .github/workflows/chromatic.yml 파일을 생성해줍니다.

name: Chromatic Deployment

on:
  push:
    branches:
      - master

jobs:
  storybook:
    runs-on: ubuntu-latest
    steps:
      - name: checkout repository
        uses: actions/checkout@v3

      - name: install depenedency
        run: npm install

      - name: deploy storybook
        uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          token: ${{ secrets.GITHUB_TOKEN }}

프로젝트 세팅에서 chromatic GitHub Actions에서 사용할 CHROMATIC_PROJECT_TOKEN에 대한 값을 추가해줍니다. 토큰 값은 chromatic 배포할 때 사용했던 토큰 값을 넣어줍니다.
GITHUB_TOKEN은 따로 지정해줄 필요없습니다.

 

위와 같이 지정해줄 경우 master 브랜치에 push 이벤트가 발생했을 경우 github action이 발생하게 됩니다.

 

하지만‼️,,

deploy storybook step에서 에러 발생

deploy storybook 에서 에러가 발생했습니다...

에러 내용을 읽어보니 checkout 과정에서 shallow copy.. 뭐뭐 문제가 있고! actions/checkout@v2와 함께라면 setting을 fetch-depth: 0으로 해줘야 되는 문구가 보였습니다. (저는 v3를 이용하긴 했지만,, 추가해줬습니다)

에러 문구

그래서 checkout step에 다음 구문을 추가해줬습니다.

- name: checkout repository
  uses: actions/checkout@v3
  with:
    fetch-depth: 0

그랬더니 말끔하게 storybook 배포에 성공했습니다.

배포 성공

배포 성공(chromatic 사이트)

 

 

 

결론

오늘, React 환경에서 Storybook을 적용하고 적용된 story를 로컬과 CI로 배포하는 과정을 살펴보았습니다. 프로젝트에 어떤 기술을 적용할 경우 우선 기술을 적용해 배포를 하고 난 뒤 점차 기술 활용 범위를 넓혀가는 것을 좋아하는터라, 오늘 설치 및 CI 배포를 마무리하여 마음이 놓이게 되었습니다. 앞으로 Storybook의 기본 사용법에 대해 알아보도록 하겠습니다.

 

 

실습한 깃허브 레포지토리 : https://github.com/beomseok37/practice-storybook

GitHub - beomseok37/practice-storybook: 이 프로젝트는 스토리북 연습 프로젝트입니다.

 

Reference

Chromatic으로 storybook 지속적 배포하기(Github Actions)

Chromatic으로 Storybook 지속적 배포하기 (Github Actions)

Storybook Docs