Frontend

Tailwind CSS v4 — 무엇이 달라졌나

한 줄 요약: Tailwind CSS v4는 설정 파일 대신 CSS 기반 설정(@theme), Rust 기반 엔진 Oxide로 빌드 속도 10배 향상, CSS-first 접근법이 핵심 변경이다. Tailwind v3에서 v4로의 전환은 단순 업그레이드가 아니라 설정 패러다임 자체가 변경된다. Tailwind CSS v4의 가장 큰 변화: 설정 파일 대신 CSS에서 직접 설정.

by Lee발행: 2026-04-04

한 줄 요약: 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 실행 후 수동으로 커스텀 설정만 점검하면 된다.

자주 묻는 질문

다른 대안과 비교했을 때 어떤 상황에 적합한가요?

새 프로젝트를 처음부터 시작한다면 v4가 분명한 선택입니다. tailwind.config.js 없이 CSS @theme 디렉티브로 설정하고, content 배열을 자동 감지하며, Oxide 엔진 덕에 대규모 빌드가 수 초에서 수백 밀리초로 줄어들기 때문입니다. CSS nesting이나 3D 트랜스폼 같은 신규 유틸리티도 바로 쓸 수 있습니다. 반대로 이미 가동 중인 v3 프로젝트라면 의존하는 서드파티 플러그인이 모두 v4 호환 버전을 냈는지가 전환 가능 여부를 가릅니다. daisyUI·headlessUI처럼 호환 버전이 나온 라이브러리만 쓴다면 npx @tailwindcss/upgrade로 전환할 만하지만, 미지원 플러그인이 핵심에 박혀 있거나 theme() 함수에 깊게 의존하는 코드가 많다면 호환 버전이 나올 때까지 v3 유지가 안전합니다.

더 깊게 공부하려면 어떤 자료를 보면 좋을까요?

출발점은 Tailwind CSS 공식 문서의 Upgrade guide 페이지입니다. v3 대비 무엇이 바뀌었는지, npx @tailwindcss/upgrade가 자동으로 처리하는 범위와 수동 점검이 필요한 항목을 항목별로 정리해 둡니다. 그다음 공식 문서의 Theme variables 페이지를 읽으면 @theme 디렉티브로 색상·폰트·breakpoint를 CSS 변수로 정의하는 방식을 정확히 익힐 수 있습니다. 키워드로는 @theme, @variant dark, @apply 대체, Oxide engine을 검색하면 됩니다. 플러그인 호환성이 걱정된다면 각 플러그인(daisyUI, headlessUI 등) 깃허브 릴리스 노트에서 v4 지원 버전을 직접 확인하는 것이 가장 확실합니다.

Tailwind CSS v4, 한 줄로 정리하면 어떻게 되나요?

Tailwind CSS v4는 단순 버전업이 아니라 설정 패러다임이 바뀐 릴리스입니다. tailwind.config.js가 사라지고 CSS 안의 @theme 디렉티브로 테마를 정의하며, content 배열 설정 없이 콘텐츠를 자동 감지하고, Rust 기반 Oxide 엔진으로 빌드가 10배 이상 빨라집니다. 전환은 npx @tailwindcss/upgrade 한 번으로 대부분 자동 처리되지만, 진짜 관문은 커스텀 플러그인 호환성입니다. addUtilities·addComponents API가 바뀌었으니 쓰던 서드파티 플러그인이 v4 버전을 냈는지부터 확인하고, theme() 함수와 darkMode: 'class' 설정만 수동으로 손보면 마이그레이션이 끝납니다.

실무에서 처음 도입할 때 가장 먼저 확인할 것은 무엇인가요?

쓰고 있는 서드파티 플러그인이 v4를 지원하는지부터 확인하세요. v4는 v3와 동시에 쓸 수 없고 프로젝트 단위로 일괄 전환해야 하는데, 가장 큰 호환성 이슈가 커스텀 플러그인입니다. addUtilities·addComponents API가 바뀌었기 때문에 daisyUI·headlessUI 같은 라이브러리가 v4 호환 버전을 냈는지 먼저 봐야 합니다. 그다음 npx @tailwindcss/upgrade로 자동 마이그레이션을 돌리면 설정 대부분이 처리됩니다. 다만 tailwind.config.js가 @theme 디렉티브로 바뀌고, theme() 함수가 var(--color-primary) CSS 변수로, darkMode: 'class'가 @variant dark로 바뀌는 부분은 실행 후 수동으로 점검하시기 바랍니다.

가장 자주 발생하는 실수나 함정은 무엇인가요?

v3 습관을 그대로 가져오는 데서 대부분의 사고가 납니다. theme() 함수를 계속 쓰려다 막히는 경우가 대표적인데, v4에서는 var(--color-primary) 같은 CSS 변수로 바꿔야 합니다. tailwind.config.js를 찾아 수정하려다 파일 자체가 사라진 걸 모르고 @theme 디렉티브 대신 옛 설정을 붙드는 실수, content 배열을 굳이 다시 지정하려는 실수(v4는 콘텐츠를 자동 감지)도 흔합니다. 그리고 가장 자주 발목을 잡는 건 커스텀 플러그인입니다. v4 미지원 플러그인이 하나라도 섞이면 빌드가 깨지므로, 업그레이드 전에 의존성 목록을 훑어 호환 버전이 있는지 확인하시기 바랍니다.

tailwindcss프론트엔드스타일링v4