Tailwind v5 — CSS-only theme + container query 정식, v4 대비 5가지 변화 | 기술노트

핵심 요약

Tailwind v5는 v4의 CSS-first 컨셉을 한 단계 더. @theme를 별도 파일로 분리 권장, container query가 코어 진입, dark variant가 매체쿼리에서 attribute로, JIT 캐시 영속화, plugin API v3 안정화. 사내 5개 제품 마이그레이션 사후.

1. @theme 분리 — design token 파일 단일화

/* design-tokens.css */
@theme {
  --color-brand: oklch(64% 0.22 263);
  --font-display: "Pretendard Variable";
  --radius-card: 0.875rem;
}

/* app.css */
@import "tailwindcss";
@import "./design-tokens.css";

2. container query — @container 키워드 코어 진입

v4에서는 plugin. v5는 코어. @container/md:flex-row 같은 컴파운드 variant 표준.

3. dark variant 재설계

기본이 prefers-color-scheme에서 [data-theme="dark"] 속성으로 전환. media variant는 별도 prefix(media-dark:). 라이트/다크 토글 구현이 단순해짐.

4. JIT 캐시 영속화

.tailwind/cache 디렉토리에 클래스 인덱스. CI에서 캐시하면 콜드 빌드 4.2s → 0.8s.

5. plugin API v3

plugin이 ESM only. CommonJS legacy 제거. matchUtilities가 lazy variant 지원 — 동적 prefix 패턴 쉬워짐.

6. 마이그레이션 함정

dark: 사용량 많으면 attribute 도입 동시에 — 점진 전환 어려움
arbitrary value 파싱 변경 — 공백·괄호 처리 다름, 자동 codemod 권장
@apply 사용 코드 — v5에서도 가능하나 비권장, 점진 제거
plugin CommonJS — 의존 plugin이 v3 미대응이면 v5 못 옴