Storybook v10 & TailwindCSS v4 설정 오류 해결

제대로 나오던 스토리보드가 설정을 변경하고 preview 영역이 무한로딩하는 현상이 발생했다. 

콘솔창의 error 코드, debug-storybook.log 내역, PowerShell 의 오류 코드를 근거로 조회하면, 여러가지 원인을 추측한다.

하나 하나 해보지만 근본적으로 해결되지 않고 챗바퀴 돌듯 제자리 걸음이었다. 

AI CLI 를 통해 해결 시도도 해봤지만 역시 무한 디버깅의 늪에 빠지거나 A-B-A-B 식의 반복을 했다. 

결국 수동으로 오류 문구로 찾아서 수정하길 반복하다 해결하고 기록한다.

 

결론부터 요약하면 최신 프레임워크 간의 규격 변화로 인한 문제였다. 

 

Storybook v10.2.x

TailwindCSS v4.1.18

Vite v7.2.4

 

1. 주요 문제 상황 (Issue Summary)

• 증상: 스토리북 실행 시 프리뷰 영역 무한 로딩 및 브라우저 콘솔의 500 (Internal Server Error) 발생.
• 근본 원인: 1. Tailwind v4의 엄격한 규칙: @apply 문법 내에 스타일 정보가 없는 마커(peer, group)나 정의되지 않은 유틸리티 클래스(grid-rows-1fr) 포함 시 빌드 중단. 2. 파일 부재: 컴포넌트 파일 백업으로 인해 Vite가 의존성 스캔(Dependency Scan)에 실패. 3. 버전 충돌: 스토리북 v10과 애드온 간의 버전 불일치로 인한 설치 오류.

2. 상세 문제 및 해결 방법 목록

분류	발생한 문제점 (Error)	해결 방법 (Solution)
Tailwind v4	@apply 내 peer, group 사용 시 unknown utility class 에러	CSS에서 해당 마커 삭제 후, HTML/JS 파일의 클래스 속성에 직접 부여
Tailwind v4	grid-rows-1fr 사용 시 빌드 에러	grid-rows-[1fr] (대괄호 문법) 사용 또는 표준 CSS grid-template-rows: 1fr;로 수정
파일 구조	컴포넌트 파일 부재로 인한 500 Error	백업한 .js 및 .stories.js 파일을 src/components/ 위치로 다시 복구
의존성(NPM)	addon-essentials 설치 시 ERRESOLVE 버전 충돌	--legacy-peer-deps 옵션을 사용하여 v10.2.6 버전으로 강제 설치
빌드(Vite)	설정 변경 후에도 이전 에러가 반복되는 캐시 오염	node_modules/.vite 및 .cache 폴더 삭제 후 재시작

3. 최종 권장 작업 절차 (Action Plan)

현재 꼬인 환경을 완전히 정상화하기 위해 아래 순서대로 최종 작업을 수행했다. 

Step 1. CSS 코드 최종 수정 (style.css)

아래 세 가지 요소를 CSS에서 완전히 제거하거나 수정해야 빌드 된다.

• @apply ... peer; → peer 삭제
• @apply ... group; → group 삭제
• @apply grid-rows-1fr; → grid-rows-[1fr]; 로 수정

Step 2. 필수 애드온 설치

버전 충돌을 무시하고 v10에 맞는 애드온을 설치한다.

npm install -D @storybook/addon-essentials@10.2.6 --legacy-peer-deps

Step 3. 파일 복구 및 캐시 초기화

Vite가 읽을 수 있도록 파일을 제자리에 두고 오염된 캐시를 밀어낸다.

# 1. 백업 파일을 src/components/ 폴더로 복사 (수동 작업)
# 2. 터미널에서 캐시 삭제
rd /s /q node_modules\.vite node_modules\.cache
# 3. 스토리북 실행
npm run storybook

4. 향후 주의사항

• Tailwind v4는 기존 tailwind.config.js 기반이 아닌 Vite 플러그인(@tailwindcss/vite) 기반으로 동작하므로, main.js의 viteFinal 설정을 유지한다.
• 새로운 클래스를 @apply로 넣을 때 에러가 난다면, 해당 클래스가 Tailwind 기본 유틸리티인지 먼저 확인한다.

 

위 문제에 앞서서 @apply를 제대로 인식하지 못해 style이 깨지는 현상이 있었고 이 부분을 해결하려고 하면서 postcss.config.js 나 tailwindcss.config.js 를 설정하는 무지한 시도를 했었다. tailwindcss.config.js 는 tailwindcss v4부터는 사용하지 않는다는 걸 알고 있었지만 postcss.config.js에 대한 팁은 찾을 수가 없었다. 

 

결론은 main.js 에 아래 코드를 추가해서 해결했다. 

import tailwindcss from '@tailwindcss/vite';

  // PostCSS 설정을 Vite가 자동으로 읽도록 보장

  viteFinal: async (config) => {

    config.plugins = config.plugins || [];

    config.plugins.push(tailwindcss()); // Tailwind v4 플러그인 주입

    return config;

  },