테크·3 min read
Tailwind v4 마이그레이션 체크리스트
Tailwind CSS v3에서 v4로 마이그레이션하는 방법을 단계별 체크리스트로 정리했습니다.
Tailwind v4의 주요 변경점
Tailwind CSS v4는 기존 설정 파일 기반에서 CSS-first 접근으로 큰 전환을 했습니다.
달라진 점 요약
| 항목 | v3 | v4 |
|---|---|---|
| 설정 파일 | tailwind.config.js | CSS @theme |
| 임포트 | @tailwind base/components/utilities | @import "tailwindcss" |
| PostCSS 플러그인 | tailwindcss | @tailwindcss/postcss |
| 커스텀 테마 | JS config 객체 | CSS 변수 + @theme |
| JIT 엔진 | Rust (Oxide) | 기본 내장 |
마이그레이션 체크리스트
1단계: 의존성 업데이트
npm uninstall tailwindcss postcss autoprefixer
npm install tailwindcss@4 @tailwindcss/postcss
2단계: PostCSS 설정 변경
// postcss.config.mjs
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
3단계: CSS 임포트 변경
/* Before (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* After (v4) */
@import "tailwindcss";
4단계: 테마 마이그레이션
/* Before (tailwind.config.js) */
module.exports = {
theme: {
extend: {
colors: {
brand: '#2563eb',
},
},
},
};
/* After (globals.css) */
@theme inline {
--color-brand: #2563eb;
}
5단계: content 경로 제거
v4는 자동 콘텐츠 감지를 합니다. tailwind.config.js의 content 배열이 불필요합니다.
6단계: 삭제된 유틸리티 확인
일부 유틸리티가 변경되었습니다:
bg-opacity-50→bg-black/50(이미 v3에서 지원)text-opacity-75→text-white/75
7단계: 플러그인 확인
@tailwindcss/forms→ v4 호환 버전 확인@tailwindcss/typography→ CSS 기반으로 재구현 필요 여부 확인
자동 마이그레이션 도구
npx @tailwindcss/upgrade
프로젝트의 대부분을 자동으로 변환해줍니다. 다만 수동 확인은 필수.
주의사항
darkMode: 'class'설정은 v4에서 기본 동작이 다름@apply사용을 줄이는 것이 권장됨 — v4는 CSS 변수 활용 장려- Tailwind v4는 Node 18+ 필요
- 빌드 속도가 대폭 개선 — Rust 엔진 기본 내장
결론
v4 마이그레이션은 대부분 자동화 도구로 처리 가능합니다. 가장 큰 변화는 설정 파일이 CSS로 이동한 것이고, 이는 장기적으로 더 직관적인 방식입니다.