🍋 install
install 하기 전에 블로그 몇 개와 공식문서 그리고 한글 번역 튜토리얼을 찾아봤는데 다르다는 걸 느꼈다.
yarn add global @storybook/cli
npx sb init
현재 공식문서에는 보이지 않는 방식이라 슬슬 혼동이 오는 나..
기존의 프로젝트에서 Storybook을 사용해서 리팩토링 하려는 방식과 새로 프로젝트 생성할 때부터 Storybook을 사용하는 방식이 다를까봐..
심지어 공식문서에 보이지 않는데 gpt가 자꾸 공식문서에 나온 이라고 언급하길래 찾아서 몇 번째 줄인지 알려줘! 라고 했는데 없다고 대답이 돌아왔다. 내 눈에만 안 보이는 줄..
결론
1. Storybook를 깐 적 없는 프로젝트 (시작, 중간 상관없음)
npm create storybook@latest
2-1. Storybook를 이미 있는 프로젝트에서 버전 업/마이그레이션할 때.
npx storybook@latest upgrade
2-2. 수동 마이그레이션
npm install --save-dev @storybook/{프레임워크}🔥 업그레이드 명령은 레포 루트에서 실행해야 모든 스토리북 패키지/설정을 제대로 찾음
2024 하반기부터 이렇게 바뀌었다고 한다.
Storybook 8 버전부터는 create-storybook 패키지로 통합되어, 새 프로젝트 초기화나 기존 프로젝트에 Storybook을 추가할 때 위와 같은 하나의 통일된 명령어로 실행하도록 개선됬다고 한다.
Storybook 7 이하는 create-storybook 패키지가 없었고, storybook CLI 자체가 init 명령을 제공했기 때문에 오래된 블로그 글이나 예제 코드에서는 아직도 이 버전의 명령을 볼 수 있다.
🍋 뭐가 다르지?
📁 예전 구조 (Storybook 7 이하)
my-project/
├── package.json
├── node_modules/
│ ├── @storybook/react/
│ │ ├── dist/
│ │ └── ...
│ └── @storybook/cli/ ← CLI 명령어가 여기 포함되어 있음
│ ├── bin/
│ │ └── sb.js ← npx sb init 실행 시
│ └── generators/ ← 각 프레임워크별 설치 로직
├── .storybook/ ← init 실행 시 생성됨
│ ├── main.js
│ ├── preview.js
│ └── manager.js
└── src/
└── *.stories.js
CLI(@storybook/cli)가 init이라는 명령어를 내장하고 있어서, 명령을 실행하면 Storybook을 자동으로 세팅해줬다.
npx storybook@latest init
npx sb init //짧게문제점
React,Next,Vite 등 프레임워크가 다양해지면서 CLI 안에 모든 설정 로직을 넣기 힘들어지고 Node.js 생태계가 create-* 패턴(create-react-app, create-next-app, create-vite 등) 으로 표준화됨
생성기(generator) 역할을 하는 별도 패키지로 분리 를 선택한 것이다.
📁 현재 구조
CLI가 분리되어 독립 패키지(create-storybook)가 되었다.
my-project/
├── package.json
├── node_modules/
│ ├── create-storybook/ ← 생성기 전용 패키지 (임시 설치)
│ │ ├── templates/ ← 프레임워크별 템플릿 코드
│ │ ├── detectFramework.js
│ │ ├── setupFiles.js
│ │ └── index.js ← npm create storybook 실행 진입점
│ ├── @storybook/react/
│ ├── @storybook/addons/
│ ├── @storybook/nextjs/
│ └── ...
├── .storybook/ ← 생성기로 만들어진 설정 폴더
│ ├── main.ts
│ ├── preview.ts
│ └── manager-head.html
└── src/
node_modules/
│ ├── create-storybook/ ← 생성기 전용 패키지 (임시 설치)
│ │ ├── templates/ ← 프레임워크별 템플릿 코드
│ │ ├── detectFramework.js
│ │ ├── setupFiles.js
│ │ └── index.js 이부분은 임시 경로(npx/npm-create 캐시) 에 받아서 실행하고 끝나기 때문에 프로젝트 루트의 package.json이나 node_modules에 create-storybook이 상주하지 않고 바로 정리된다.
이런 흐름
- npm create storybook@latest 입력
- npm이 임시 폴더에 create-storybook 설치
- create-storybook/index.js 실행
├─ detectFramework() → 프레임워크 감지
├─ copyTemplates()
├─ installPackages()
└─ npm script 등록 - 생성기 실행 완료 후 제거
- 프로젝트 안에는 Storybook 설정과 패키지만 남음
