Storybook v8 preset 에러 트러블슈팅

최근 Storybook v8을 도입했는데, 계속 preset을 찾지 못하는 문제가 발생했다. 해결은 허무할 만큼 단순했지만, 원인을 찾아가는 과정을 간단하게 정리해 보았다.

문제 상황

예상 경로

packages/design-system/
├── .storybook/
└── preset.js  # 여기에 있는 파일을 찾아야 함

실제 탐색 경로

project-root/
├── node_modules/@storybook/core/  # 여기서 실행되어
└── ??? # 루트에서 preset을 찾으려고 시도

분명히 design-system 워크스페이스 안에 있는 preset을 읽어야 하는데, Storybook은 루트에서만 찾으려 했다. 어떤 이유에서 에러가 발생하는지 감이 안 잡혀서 일단 의존성을 확인해 보았다.

─ storybook@npm:8.6.14
│  └─ @storybook/core@npm:8.6.14 (via npm:8.6.14)
│
└─ storybook@npm:8.6.14 [a_id]
   └─ @storybook/core@npm:8.6.14 [b_id] (via npm:8.6.14 [b_id])

왜 버전이 두 개나 나올까..? 궁금해져서 찾아봤는데 Yarn Berry는 peerDependencies를 충족하는 컨텍스트가 다르면 같은 버전이라도 virtual package로 분리하기 때문에, @storybook/core@8.6.14가 두 줄로 보인다.

• [a_id], [b_id] 같은 건 Yarn이 붙이는 virtual package ID다.
• 실제 디스크에는 하나만 설치된다.
• Yarn이 안전하게 의존성을 격리하기 위해 논리적으로만 분리하는 것.

그럼 왜 굳이 논리적으로 분리할까?

• 팬텀 의존성 방지: 선언하지 않은 패키지를 몰래 가져다 쓰는 문제 차단
• peerDependencies 안정성 확보: React 17과 React 18처럼 context마다 peer 요구가 다를 수 있음
• 버전 충돌 대비: 나중에 일부 워크스페이스가 8.7.0을 요구하더라도 충돌 없이 공존 가능

같은 버전이 두 번 나온 이유는 실제 이슈와 직접적인 상관은 없었지만, 찾는 과정에서 Yarn의 virtual package 개념을 다시 알게 되었다.

해결 방법

해결 방법은 너무 허무했는데 캐시를 날리고 다시 설치를 해서 해결하였다...

( ++ 삽질하다가 문득 예전 회사 팀원분들과 자주 주고받던 '혹시 캐시 날려보셨어요?' 가 생각나서 했더니 해결됐다.)

해결 후에 찾은 나와 비슷한 관련 GitHub 이슈 코멘트에도 같은 해결 방법이 언급되어 있었다.

+++ yarn 호이스팅에 대해서도 추가적으로 정리해 보았다.

Yarn Workspaces의 핵심: 호이스팅

Yarn Workspaces는 모노레포에서 여러 프로젝트가 공통으로 사용하는 의존성을 루트 node_modules로 끌어올린다.

monorepo/
├── node_modules/          # 모든 의존성이 여기로 호이스팅
│   ├── react/
│   ├── lodash/
│   └── @storybook/core/
├── yarn.lock              # 전체 의존성 잠금
├── package.json
└── packages/
    ├── design-system/
    │   └── package.json   # react, @storybook/core 선언
    └── web-app/
        └── package.json   # react, lodash 선언

호이스팅의 이점

• 중복 설치 방지 → 디스크 공간 절약
• 설치 시간 단축
• 전체 모노레포의 의존성 일관성 보장

yarn.lock의 역할

• 루트에만 생성되며, 모든 워크스페이스 의존성을 통합 관리
• 버전 충돌 방지
• CI/CD 환경에서 동일한 의존성 트리 보장

nohoist vs nmHoistingLimits

특정 패키지는 호이스팅 되면 문제가 생길 수 있는데, Yarn은 이를 제어할 수 있는 옵션을 제공한다.

1. Yarn Classic(v1) → nohoist

{
  "workspaces": {
    "packages": ["packages/*"],
    "nohoist": [
      "**/react-native",
      "**/react-native/**"
    ]
  }
}

2. Yarn Berry(v2+) →. yarnrc.yml

nmHoistingLimits: workspaces

nohoist와 nmHoistingLimits는 같은 개념의 다른 버전 옵션이다. v1인지 v2+인지 확인하고 맞는 설정을 사용해야 한다.

트러블슈팅 체크리스트

--> 비슷한 문제가 다시 생겼을 때 빠르게 점검할 수 있도록 체크리스트를 정리해 두었다.

1. 캐시 정리부터
2. yarn cache clean yarn install
3. yarn.lock 상태 확인 (필요시 삭제 후 재생성)
4. 워크스페이스 구조 확인 → yarn workspaces info
5. 호이스팅 동작 확인
6. 의존성 그래프 분석 → yarn why [패키지명]

https://yarnpkg.com/advanced/lexicon#virtual-package

https://www.docs4dev.com/docs/yarn/berry/advanced/architecture.html?utm_source=chatgpt.com

https://classic.yarnpkg.com/blog/2018/02/15/nohoist/