Tailwind CSS v4 — 무엇이 달라졌나

한 줄 요약: Tailwind CSS v4는 설정 파일 대신 CSS 기반 설정(@theme), Rust 기반 엔진 Oxide로 빌드 속도 10배 향상, CSS-first 접근법이 핵심 변경이다.

Tailwind v3에서 v4로의 전환은 단순 업그레이드가 아니라 설정 패러다임 자체가 변경된다. tailwind.config.js가 CSS @theme 디렉티브로 대체되고, PostCSS 플러그인 없이 독립 실행이 가능해졌다.

v4의 핵심 변화

Tailwind CSS v4의 가장 큰 변화: 설정 파일 대신 CSS에서 직접 설정. tailwind.config.js가 사라지고 @theme 디렉티브로 CSS 안에서 커스터마이징합니다. 빌드 속도도 Rust 기반 엔진으로 대폭 향상.

CSS-first 설정: tailwind.config.js 대신 CSS 파일에서 직접 테마를 정의한다. @theme { --color-primary: #8B5CF6; --font-sans: 'Inter', sans-serif; }처럼 CSS 변수로 설정하므로, IDE의 CSS 자동완성과 디버깅 도구가 그대로 동작한다.

Tailwind v4 CSS 기반 설정
/* app.css */
@import "tailwindcss";

@theme {
  --color-primary: #8B5CF6;
  --color-secondary: #06B6D4;
  --font-sans: 'Inter', sans-serif;
  --breakpoint-3xl: 1920px;
}

Oxide 엔진: Rust로 재작성된 빌드 엔진은 CSS 생성 속도를 10배 이상 향상시킨다. 대규모 프로젝트에서 빌드 시간이 수 초에서 수백 밀리초로 단축된다. 또한 콘텐츠 감지가 자동화되어 content 배열 설정이 불필요해졌다.

새로운 기능들

@theme 디렉티브: CSS 네이티브 설정
자동 콘텐츠 감지: content 배열 불필요
네이티브 중첩: CSS nesting 지원
3D 트랜스폼 유틸리티: rotate-x, perspective 등

v3에서 마이그레이션

공식 마이그레이션 도구: npx @tailwindcss/upgrade. 자동으로 대부분의 변경사항을 처리해주지만, 커스텀 플러그인은 수동 확인이 필요합니다.

v3에서 v4로 마이그레이션

npx @tailwindcss/upgrade 명령으로 자동 마이그레이션이 가능하다. 주요 변경사항: 1) @apply는 유지되지만 권장되지 않음 2) theme() 함수 대신 CSS 변수 var(--color-primary) 사용 3) 커스텀 플러그인 API 변경 4) darkMode: 'class' 설정이 @variant dark로 변경

가장 큰 호환성 이슈는 커스텀 플러그인이다. v3 플러그인의 addUtilities, addComponents API가 변경되었으므로, 서드파티 Tailwind 플러그인이 v4를 지원하는지 확인해야 한다. 주요 라이브러리(daisyUI, headlessUI)는 이미 v4 호환 버전을 출시했다.

마이그레이션 팁: v3와 v4를 동시에 사용할 수는 없다. 마이그레이션은 프로젝트 단위로 일괄 진행해야 하며, npx @tailwindcss/upgrade 실행 후 수동으로 커스텀 설정만 점검하면 된다.

Tailwind CSS v4 — 무엇이 달라졌나

v4의 핵심 변화

새로운 기능들

v3에서 마이그레이션

v3에서 v4로 마이그레이션

관련 도구

관련 포스트