Next.js 14에서 Tailwind와 Storybook을 함께 사용하기 위한 호환성 문제 및 해결 방법
(최신 내용으로 업데이트 2024. 8.15)
Storybook 최신 버전 8을 tailiwdCSS와 연동하여 사용하는 경우 tailwind가 적용이 안되는 이슈가 있습니다. Storybook 깃 레포의 이슈탭에는 아직도 여전히 처리가 되지 않고 있다. stable release가 3월에 되었지만 최초 버그가 제기된 이후로 여전히 해결이 되지 않고 있어 최신 Storybook에서 사용이 안되고 있습니다.
최근 프로젝트에서 Next.js 14, Tailwind CSS와 Storybook을 결합하여 디자인 시스템을 구축하려는 시도를 했습니다. 그러나 Storybook의 최신 버전(8.x)을 사용했을 때 Tailwind CSS가 제대로 동작하지 않는 문제가 발생했습니다. 많은 개발자들이 이와 같은 호환성 문제를 겪고 있으며, 이에 대한 해결 방법을 공유하려 합니다.
이 글에서는 Storybook의 7.6.17 버전을 사용하여 Next.js 14와 Tailwind CSS의 호환성을 확보하고, 프로젝트 설정 과정에서 발생할 수 있는 문제들을 해결하는 방법을 설명합니다.
1. 스토리북 최신 버전 8.x의 호환성 문제
Storybook의 최신 버전인 8.x에서는 Next.js 14와 Tailwind CSS를 결합한 프로젝트에서 CSS가 제대로 적용되지 않는 문제가 발생할 수 있습니다. 특히, Tailwind의 테마와 관련된 CSS가 Storybook에서 렌더링되지 않아 스타일이 깨지거나 전혀 적용되지 않는 경우가 있습니다.
문제 원인:
Storybook 8은 Tailwind의 PostCSS 처리 방식과 충돌하거나, Tailwind의 테마 설정이 Storybook의 스타일 처리 흐름에서 올바르게 로드되지 않는 것이 주요 원인으로 보입니다. 이 문제는 공식적으로 해결되지 않은 상태이기 때문에, 현재로서는 Storybook 7.6.17 버전을 사용하는 것이 가장 안정적인 해결책입니다.
그렇기 때문에 Next.js 14를 기준으로 tailwindCSS와 Storybook을 사용하기 위한 방법은 호환이 되는 버전끼리 사용하는 방법입니다. 첫번째는 Storybook 버전을 다운그레이드 해서 사용하는 것이고, 두번째는 Storybook 8버전을 사용하되 현재 storybook 이슈 탭에서 공유된 방법으로 호환버전을 맞춰서 사용하는 것입니다.
2. Storybook 7.6.17로 다운그레이드하기
다행히, Storybook 7.6.17 버전에서는 Tailwind CSS가 정상적으로 동작합니다. 하지만 단순히 Storybook 버전을 다운그레이드한다고 해서 문제가 바로 해결되는 것은 아닙니다. 프로젝트 설정에 몇 가지 추가적인 작업이 필요합니다.
해결 방법:
- Storybook 7.6.17 설치:기존에 설치된 Storybook 8.x 버전이 있다면, 이를 먼저 삭제하고 7.6.17로 재설치해야 합니다. Storybook 7.x와 8.x 간의 설정 파일 차이도 있기 때문에, 새로운 설정을 적용할 필요가 있습니다.
-
bash코드 복사npx sb init npm install @storybook/react@7.6.17
- Next.js + Tailwind 프로젝트 설정: Next.js와 Tailwind를 결합한 프로젝트를 설정합니다. 이는 기본적으로 PostCSS와 Tailwind 설정 파일을 포함하게 됩니다.
-
bash코드 복사npx create-next-app@latest my-nextjs-app cd my-nextjs-app npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -p
- Storybook과 Tailwind 연동: Storybook에 Tailwind를 적용하기 위해 preview.js 파일에서 Tailwind 설정을 포함시킵니다. 아래와 같이 Storybook의 preview.js에서 Tailwind의 스타일을 불러옵니다.
-
javascript코드 복사import '../styles/globals.css'; // Tailwind CSS 로드
- 설치된 패키지 정리: 특정 호환성 문제를 해결하기 위해서는 node_modules 폴더와 package-lock.json을 삭제한 후 패키지를 다시 설치하는 것이 중요합니다.이렇게 하면 종속성 충돌이나 캐싱 문제로 인해 발생하는 오류를 방지할 수 있습니다.
-
bash코드 복사rm -rf node_modules package-lock.json npm install
3. 이슈 해결 후 기대되는 효과
이 과정을 통해 Next.js 14, Tailwind CSS, Storybook을 결합한 환경에서 안정적으로 디자인 시스템을 운영할 수 있습니다. Storybook 7.6.17은 최신 버전의 기능을 지원하면서도 Tailwind CSS와 호환성을 보장하기 때문에, 디자인 컴포넌트의 문서화와 테스트 작업이 원활해집니다.
성능 및 유지보수:
- 재사용성: Storybook을 활용한 컴포넌트의 문서화 및 스토리 제작을 통해 재사용성과 유지보수성을 크게 향상시킬 수 있습니다.
- 일관성: Tailwind CSS의 유틸리티 기반 스타일링을 사용해 프로젝트 전반에 걸쳐 일관된 스타일 가이드를 유지할 수 있습니다.
- 효율성: 문제를 사전에 해결하여 개발 시간을 절약하고, 안정적인 디자인 시스템을 구축하는 데 도움을 줍니다.
결론
Next.js 14와 Tailwind CSS를 사용해 웹사이트를 구축하고, Storybook을 통해 컴포넌트 기반 디자인 시스템을 구축하는 것은 강력한 전략입니다. 하지만 Storybook의 최신 버전 8.x와의 호환성 문제로 인해 CSS가 제대로 표시되지 않는 이슈가 있을 수 있으며, 이를 해결하기 위해서는 Storybook 7.6.17 버전을 사용하는 것이 바람직합니다.
또한, 단순히 버전을 다운그레이드하는 것만으로는 문제가 해결되지 않으므로, 프로젝트의 종속성을 정리하고 Tailwind와 Storybook 간의 연동을 올바르게 설정해야 합니다. 이 과정을 통해 문제를 해결하고, 보다 안정적인 환경에서 개발을 진행할 수 있을 것입니다.
관련 패키지 버전:
- Next.js: 14.x
- Storybook: 7.6.17
- Tailwind CSS: 최신 버전
이 가이드를 통해 동일한 문제를 겪는 개발자들이 보다 쉽게 문제를 해결할 수 있기를 바랍니다.
