Tailwind v4 나왔는데 마이그레이션 하셨어요?

v3에서 v4로 넘어가면서 바뀐 게 꽤 많아요. 설정 파일부터 문법까지요.

뭐가 달라졌나

1. CSS-first 설정

가장 큰 변화예요. tailwind.config.js 안 써도 돼요.

CSS 파일 하나로 끝나요.

2. @tailwind → @import

한 줄로 줄었어요.

3. 네이티브 CSS 변수

v4는 모든 값을 CSS 변수로 생성해요.

Tailwind 클래스 안 쓰고 CSS에서 직접 변수 쓸 수 있어요. 디자인 토큰을 다루는 입장에서는 이게 제일 반가운 변화예요.

마이그레이션 방법

Step 1. 패키지 업그레이드

Step 2. CSS 파일 변경

Step 3. config 옮기기 (선택)

기존 설정이 있다면 CSS로 옮기거나 그대로 둬도 돼요.

둘 다 가능해요. 점진적으로 CSS로 옮겨도 되고요.

바뀐 문법들

그대로인 것

opacity 문법과 arbitrary 값은 v3와 똑같아요.

여기서 고칠 건 없어요.

container queries

v4에서 기본 지원돼요.

3D transforms

자주 발생하는 오류

1. PostCSS 설정

tailwindcss 대신 @tailwindcss/postcss 써야 해요. 마이그레이션하고 스타일이 통째로 안 먹으면 십중팔구 여기예요.

2. @apply 경고

v4는 @apply 사용을 권장하지 않아요. CSS 변수 쓰는 게 나아요.

3. 플러그인 호환성

일부 v3 플러그인이 v4에서 안 될 수 있어요. 확인이 필요해요.

언제 마이그레이션할까

지금 해도 되는 경우

새 프로젝트
커스텀 설정 거의 없는 프로젝트
CSS 변수 적극 활용하고 싶은 경우

좀 기다려야 하는 경우

레거시 플러그인 많이 쓰는 경우
@apply 엄청 많이 쓰는 경우
안정성이 최우선인 프로덕션

v4의 장점

빌드 속도 — Oxide 엔진으로 훨씬 빨라졌어요
설정 간소화 — CSS-first로 설정 파일이 줄어요
CSS 변수 네이티브 — 디자인 토큰 활용이 쉬워져요
번들 크기 — 더 최적화됐어요

정리

v4 마이그레이션 체크리스트예요.

tailwindcss@latest 설치
@tailwind → @import "tailwindcss" 변경
postcss.config.js 업데이트
커스텀 설정 @theme으로 옮기기 (선택)
플러그인 호환성 확인
@apply 경고 확인

급하게 할 필요 없어요. v3도 당분간 유지보수될 거예요. 새 프로젝트부터 v4 쓰고, 기존 프로젝트는 천천히 마이그레이션하면 돼요.

Tailwind CSS v4 마이그레이션 가이드