Tailwind CSS가 버전 4로 업그레이드되면서 많은 변화가 있었습니다. 이번 글에서는 Tailwind CSS 버전 4로 마이그레이션하며, Tailwind 기반 UI 라이브러리인 Flowbite와 Flowbite-React를 적용하는 과정에서 겪은 에러와 그 해결 방법을 공유하고자 합니다.
1. Tailwind CSS 4 설치 및 기본 변경사항
공식 문서의 🔗 Tailwind CSS 설치 가이드 Get started with Tailwind CSS를 참고하여 프로젝트에 Tailwind CSS (^4)를 설치합니다.
버전 3에서 4로 업데이트되면서 가장 눈에 띄는 변경 사항은 app.css 파일 내의 설정입니다.
기존의 아래 코드에서:
/* ver 3 의 기존 코드 */
/* @tailwind base; */
/* @tailwind components; */
/* @tailwind utilities; */
/* ver 4 의 변경된 코드 */
@import "tailwindcss";
2. Flowbite 및 Flowbite-React 설치
Tailwind CSS 설치 후, Flowbite와 Flowbite-React를 설치합니다.
npm install flowbite flowbite-react프레임워크 별 자세한 실행 방법은 🔗 Flowbite-React 공식 문서를 참고해주세요.
3. Tailwind CSS 4 + Flowbite-React 환경 구성
공식 Flowbite 문서에 따르면 Flowbite는 Tailwind CSS 4를 지원합니다.
하지만 Flowbite-React의 경우 아직 마이그레이션 가이드가 제공되지 않고 있습니다.
하지만 plugin 에 Flowbite-React 를 넣으면 되지 않을까? 하는 실험적인 접근을 시도해보았습니다.
// tailwind.config.ts
import flowbitePlugin from 'flowbite/plugin';
import flowbite from 'flowbite-react/tailwind';
import type { Config } from 'tailwindcss';
export default {
content: [
'./src/app/**/*.{js,ts,jsx,tsx,mdx}',
flowbite.content(),
],
theme: {},
plugins: [flowbitePlugin],
} satisfies Config;4. Flowbite-React CSS 일부 적용 안되는 문제
Flowbite에서 정의한 Button은 정상적으로 동작하지만, Flowbite-React 관련 CSS는 Tailwind CSS가 인식하지 못하고 있었습니다.
Flowbite-React의 Button 컴포넌트를 사용했을 때, 텍스트 색상 등은 정상적으로 적용되지만 배경색, 패딩 등 일부 CSS가 적용되지 않는 문제가 발생했습니다.
import { Button } from "flowbite-react";
export default function App() {
return (
<div className="bg-sky-200 h-full flex flex-col items-center justify-center gap-5">
<Button>Flowbite React Button</Button>
<button
type="button"
className="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 me-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800"
>
Flowbite Button
</button>
</div>
);
}개발자 도구로 디버깅
개발자 도구를 통해 확인해본 결과, class에 p-0.5, px-4, py-2 등의 클래스가 포함되어 있음에도 스타일이 적용되지 않았습니다.
| 개발자 도구 | element | style |
|---|---|---|
| img |  |  |
tailwind cli 로 output.css 확인
tailwindcss/cli 를 설치하고 css 가 어떻게 적용되고 있는 지 output.css 파일을 살펴보았습니다.
npx @tailwindcss/cli -i ./src/[@tailwind.css 가 들어있는 파일 경로]/app.css -o ./src/output.css --watch
확인 결과 p-0.5, px-4, py-2 등이 생성되고 있지 않았습니다.
5. 문제 원인: Legacy tailwind.config.js
Flowbite-React 관련 CSS는 Tailwind CSS가 인식하지 못하고 있었습니다.
import flowbitePlugin from "flowbite/plugin";
import flowbite from "flowbite-react/tailwind";
import type { Config } from "tailwindcss";
console.log("flowbite", flowbite, flowbite.content());
export default {
content: [
"./src/app/**/*.{js,ts,jsx,tsx,mdx}",
"./src/shared/ui/**/*.{js,ts,jsx,tsx,mdx}",
"./src/views/**/*.{js,ts,jsx,tsx,mdx}",
"./src/widgets/**/*.{js,ts,jsx,tsx,mdx}",
flowbite.content(),
],
theme: {},
plugins: [flowbitePlugin],
} satisfies Config;tailwind.config.ts에 flowbite.content() 를 추가하였지만, 실제 파싱은 이루어지지 않았습니다.
/* app.css */
@import "tailwindcss";
@config "./tailwind.config.ts";그리고 app.css 파일에 @config "./tailwind.config.ts"; 를 추가했으나, Tailwind CLI로 output.css 를 재확인 시 content를 읽지 못하는 에러가 발생했습니다.
TypeError: Cannot read properties of undefined (reading 'content')공식 문서를 확인한 결과, Tailwind CSS 4에서는 tailwind.config.js/ts 파일이 레거시 방식으로 취급되며, 대신 @config 지시어를 통해 참조해야 한다는 점을 알게 되었습니다.
Use the @config directive to load a legacy JavaScript-based configuration
tailwind.config.ts 는 레거시 파일이 되었고 그 안의 content, plugin, theme 등은 @ 로 app.css 파일에 직접 추가하도록 변경되었습니다.
https://tailwindcss.com/docs/functions-and-directives#source-directive
이전에는 tailwind.config.ts 파일에 content 로 경로를 입력해야했던 방식에서 tailwind 에서 자동으로 파일을 감지하여 css 가 적용됩니다.
tailwind css 의 자동 콘텐츠 감지에 포착되지 않은 소스 파일을 명시적으로 지정하려면 @source 로 경로를 지정할 수 있습니다.
따라서 flowbite-react 경로를 직접 @source 로 적용해주었습니다.
plugin 역시 tailwind.config.ts 파일이 아닌 @plugin 으로 직접 적용해주었습니다.
/* app.css */
@import "tailwindcss";
/* @config "./tailwind.config.ts"; 삭제 */
@source "./node_modules/flowbite-react/dist/esm/**/*.mjs";
@plugin "flowbite/plugin";
output.css
tailwindcss cli 를 다시 활용해 output.css 를 다시 확인해본 결과 이번엔 누락되었던 p-0.5, px-4 등이 잘 생성되었습니다.
6. 최종 해결 방법
문제 해결을 위해 아래와 같이 변경하였습니다.
- tailwind.config.ts 파일 삭제
- Flowbite 플러그인은 @plugin으로 app.css에 직접 추가
- Flowbite-React 관련 경로는 tailwind.config.ts 대신 @source로 app.css에 직접 추가
최종 app.css 파일은 다음과 같이 구성되었습니다.
// app.css
@import "tailwindcss";
@plugin "flowbite/plugin";
@source "./node_modules/flowbite-react/dist/esm/**/*.mjs";import "./app.css";
import { Button } from "flowbite-react";
export default function App() {
return (
<div className="bg-sky-200 h-full flex flex-col items-center justify-center gap-5">
<Button>Flowbite React Button</Button>
<button
type="button"
className="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 me-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800"
>
Flowbite Button
</button>
</div>
);
}적용 후, Tailwind CLI를 다시 실행하여 output.css를 확인한 결과, 누락되었던 p-0.5, px-4 등의 클래스가 정상적으로 생성됨을 확인할 수 있었습니다.
최종 결과, Flowbite-React에서 import한 Button 컴포넌트도 CSS가 정상적으로 적용되어 원하는 스타일을 얻을 수 있었습니다.
