Tailwind CSS v4 마이그레이션 — Oxide 엔진과 CSS 변수 기반 테마 시스템 도입기

Tailwind CSS v4는 Rust 기반 Oxide 엔진 도입과 CSS 변수 네이티브 지원으로 v3 대비 큰 변화를 가져왔습니다. 실전 마이그레이션 경험 정리.

v4 핵심 변경점

1. 1Oxide 엔진: Rust 기반, 빌드 5배 빨라짐
2. 2CSS 변수 네이티브: @theme 블록에서 직접 정의, JS config 선택적
3. 3Zero-config 시작: tailwind.config.js 없이 동작 가능
4. 4컨테이너 쿼리 표준: 별도 플러그인 불필요
5. 53D/subgrid 유틸: CSS 최신 기능 기본 지원

신규 프로젝트 셋업

/* globals.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.7 0.15 250);
  --font-display: "Pretendard", sans-serif;
  --radius-md: 0.5rem;
}

tailwind.config.js 없이 이것만으로 동작. 훨씬 간결.

v3 → v4 마이그레이션 체크리스트

1단계: 업그레이드

npm install tailwindcss@4 @tailwindcss/postcss@4 --save-dev
# Vite 사용 시
npm install @tailwindcss/vite --save-dev

2단계: 설정 파일 변환

npx @tailwindcss/upgrade 실행 → tailwind.config.js 자동 마이그레이션.

3단계: CSS 변수로 점진 이전

/* v3 방식 (유지 가능) */
/* tailwind.config.js의 theme.extend */

/* v4 방식 (권장) */
@theme {
  --color-primary-500: #3b82f6;
  --breakpoint-xs: 480px;
}

4단계: PostCSS 설정

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

기존 tailwindcss와 autoprefixer 별도 불필요. Oxide가 둘 다 처리.

주요 Breaking Changes

1. 1@apply 제한: 임의 클래스 체이닝 불가. 토큰 수준만 허용
2. 2JIT 옵션 제거: 항상 JIT 모드. 레거시 모드 폐기
3. 3deprecated 유틸: flex-shrink-0 → shrink-0 등 축약 이름만 유지
4. 4@variants, @responsive 지시어 제거: 미디어 쿼리는 표준 CSS 문법으로

실전 빌드 속도 비교

컴포넌트 300개 프로젝트:

• v3 + PostCSS: 초기 빌드 8.2초
• v4 + Oxide: 초기 빌드 1.4초
• 증분 빌드: v3 1.2초 → v4 0.3초

큰 디자인 시스템일수록 체감 차이 극대화.

CSS 변수 테마 장점

런타임 테마 변경 즉시 반영:

document.documentElement.style.setProperty("--color-brand", "oklch(0.5 0.2 30)")

다크모드·브랜드 커스터마이제이션·A/B 테스트 CSS 변수만 바꾸면 전역 즉시 반영. 재빌드 불필요.

주의할 호환성 이슈

1. 1daisyUI·Flowbite 등 UI 라이브러리: v4 호환 버전 대기 필요
2. 2CVA(class-variance-authority): 최신 버전에서만 v4 지원
3. 3IDE 자동완성: VS Code Tailwind 확장 최신 업데이트 필수

마무리

Tailwind v4는 Zero-config · 빠른 빌드 · CSS 네이티브 세 방향이 명확한 진화입니다. 신규 프로젝트는 v4 무조건 권장. 기존 v3 대규모 프로젝트는 UI 라이브러리·플러그인 호환성 확인 후 점진 전환이 안전합니다. 마이그레이션 공식 도구(@tailwindcss/upgrade)가 90% 자동 처리하니 부담은 크지 않습니다.