[FE/Next.js/Storybook] 25.08.04 - 스토리북 적용 및 PostCSS 오류 해결

 

---

✏️ 25.08.04 - 주요 Task

• FE Storybook 도입
• Storybook 실행 중 PostCSS 관련 오류 해결
• package.json 내 "type":"module" 및 Tailwind CSS

 

---

📌 프론트엔드

✅ FE Storybook 도입

• 도입 목적
  • UI 컴포넌트 문서화와 개발 편의성 향상
  • 컴포넌트별 독립적인 테스트 및 시각화 가능
    (+ 팀 프로젝트였다면 디자이너/기획자/개발자 간 커뮤니케이션 효율화)
• 개발 중 Storybook 도입한 이유
  
  • 기존 UI 컴포넌트 테스트가 번거로웠음
  • Storyboo은 각 컴포넌트를 따로 렌더링/테스트/프리뷰할 수 있기에 생산성 향상 기대
  • 실제 서비스 반영 전, 각 컴포넌트의 상태와 조합을 테스트하기 용이
  • 사용자 시나리오별 다양한 UI 케이스를 시각적으로 확인 가능
• 이점
  • 컴포넌트 단위 개발 문화를 정착시키는 데 큰 역할을 할 수 있을듯
  • UI 버그나 스타일 이슈 초기 발견 용이
    (+ UI 라이브러리 구축이나 디자인 시스템 도입까지 확장 가능)

---

✅ Storybook 실행 중 PostCSS 관련 오류 해결 (무한 로딩 이슈)

// ❌ Incompatible format (used by Next.js)
const config = {
  plugins: ["@tailwindcss/postcss"],
};

Please transform your PostCSS config to use the object-based format, which is compatible with Next.js and Vite:

// ✅ Compatible format (works with Next.js and Vite)
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Original error: Invalid PostCSS Plugin found at: plugins[0]

(@.\postcss.config.mjs)

• 원인 분석
  
  • Next.js: plugin: [] 배열 방식의 PostCSS 설정 지원 <-> Storybook(Vite): plugins: {} 오브젝트 기반 지원
    => 서로 호환 불가
  • config 방식 불일치로 Storybook 실행 실패 => 무한 로딩되는 것으로 보여짐
• 해결방법 및 과정
  • PostCSS 설정 파일을 object 기반으로 변경
  • @storybook/addon-postcss 및 postcss 패키지를 dependency로 설치
    - @storybook/addon-postcss: Storybook이 postcss.config.cjs 파일 인식 및 CSS 플러그인 처리를 도와주는 애드온
    - 본 애드온 설치 시 Storybook 빌드 과정에서 Tailwind CSS 제대로 적용됨
  • 결과: Storybook에서 Tailwind CSS 스타일 정상적으로 적용됨

// postcss.config.cjs
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {}, // CSS에 자동으로 벤더 접두사 추가 -> 브라우저 호환성 확보 플러그인
  },
};

// install
npm install -D @storybook/addon-postcss postcss

• 배운 점
  
  • 환경별(Next.js, Vite) 설정 방식 차이에 민감해야 함
  • 공식 문서 및 에러 메시지를 읽으면 해결 실마리를 빨리 찾을 수 있음
  • 설정값 하나 차이로 빌드/실행이 막힐 수 있으니 환경 세팅 시 각 호환성 체크 중요

---

✅ package.json 내 "type":"module" 및 Tailwind CSS

• package.json에 "type":"module" 추가
  
  • 이유: ES 모듈 import/export 문법을 제대로 작성하기 위해 명시
• Tailwind CSS 유틸리티 클래스 활용
  • whitespace-pre-line: 사용자가 입력한 줄바꿈 문자를 그대로 표시하기 위함
  • break-words: 긴 단어가 넘칠 때 자동으로 줄바꿈되도록하기 위함

---

✏️ 정리하면

• FE Storybook 도입
  • 도입 목적: UI 컴포넌트 문서화, 개발 편의성 향상, 독립 테스트 (+커뮤니케이션 효율화)
  • 이점: 컴포넌트 단위 개발 문화 정착, UI 버그/스타일 이슈 조기 발견
• Storybook 실행 중 PostCSS 관련 오류 해결
  • 원인: Next.js(plugin: [])와 Storybook(Vite)의 PostCSS 설정 방식(plugins: {}) 불일치
  • 해결 방법:
    1. postcss.config.cjs를 object 기반으로 변경
    2. @storybook/addon-postcss와 postcss 패키지 설정
       (+ @storybook/addon-postcss 애드온 추가, autoprefixer 플러그인을 추가하여 브라우저 호환성 확보)
  • 배운 점: 환경별 설정 방식 차이 인지, 공식 문서 및 에러 메시지 분석의 중요성, 호환성 체크 습관화
• package.json 내 "type": "module" 및 Tailwind CSS
  • "type": "module": ES 모듈 문법(import/export)을 사용하기 위해 명시
  • Tailwind CSS: whitespace-pre-line(줄바꿈 유지)과 break-words(자동 줄바꿈) 등 활용