Tailwind CSS v4 새로운 기능 해설: 성능, 설정 및 마이그레이션 가이드

35밀리초. Tailwind v3에서 한 번의 증분 빌드에 걸리는 시간입니다. v4에서는 같은 작업이 192마이크로초면 끝납니다. 밀리초가 아니라 마이크로초입니다.

이 수치를 처음 봤을 때는 의심부터 들었습니다. 마케팅 문구야 누구나 쓸 수 있으니까요. 하지만 실제로 마이그레이션을 진행하고 HMR이 340ms에서 12ms로 빨라지는 모습을 보고 나서야 이번 Tailwind의 변화가 진짜라는 사실을 실감했습니다.

이는 Rust로 다시 작성한 Oxide 엔진이 가져온 실제 변화입니다. 단순히 ‘조금 빨라진 것 같다’는 심리적 효과가 아니라, padding을 바꾸고 눈을 깜빡이기도 전에 페이지가 새로고침되는 경험입니다. Tailwind v4는 엔진만 교체한 버전이 아닙니다. 설정 방식(JS에서 CSS로 이동), 설치 과정(설정 최소화), 유틸리티 클래스 문법(투명도 수정자, Container Queries, 3D Transforms 등)을 전면적으로 바꿨습니다.

이 글에서는 이러한 변화를 하나씩 명확히 살펴보고, 그대로 따라 할 수 있는 마이그레이션 체크리스트를 제공합니다.

Oxide 엔진 — v4는 왜 이렇게 빠를까요?

색상 값을 하나 바꾸고 저장한 뒤, 브라우저에 변경 사항이 나타날 때까지 2~3초를 기다려 본 적이 있나요? 대규모 프로젝트에서는 Tailwind v3의 증분 빌드가 꽤 답답하게 느껴질 수 있습니다. 특히 마감이 촉박할 때는 더 그렇습니다.

v4의 Oxide 엔진은 바로 이 문제를 해결하기 위해 만들어졌습니다. Tailwind 팀은 기존 JS 엔진을 조금씩 손보는 대신, Rust로 컴파일러 전체를 처음부터 다시 작성했습니다. 과감한 결정이었지만 그만큼 확실한 성과를 가져왔습니다.

성능은 정확히 얼마나 향상됐을까요?

공식 팀이 Catalyst 프로젝트로 진행한 벤치마크 결과는 매우 직관적입니다.

테스트 시나리오	v3.4	v4.0	향상 배수
전체 빌드	378ms	100ms	3.78x
증분 빌드(CSS 변경 있음)	44ms	5ms	8.8x
증분 빌드(CSS 변경 없음)	35ms	192µs	182x

마지막 수치가 특히 놀랍습니다. 새 CSS 클래스를 추가하지 않고 HTML 구조만 수정하면 v4의 빌드 시간은 마이크로초 단위까지 내려갑니다. 사람이 체감할 수 없는 수준의 지연입니다.

프로덕션 프로젝트(컴포넌트 500개 이상인 코드베이스)의 수치도 있습니다.

지표	v3.4	v4.0	변화
콜드 스타트 빌드	12.3s	1.8s	85% 빨라짐
개발 서버 시작	4.2s	0.8s	81% 빨라짐
HMR 업데이트	340ms	12ms	96% 빨라짐
프로덕션 CSS 크기	48KB	31KB	35% 감소
메모리 사용량	180MB	45MB	75% 감소

HMR이 340ms에서 12ms로 줄어든 변화는 개발 경험에 큰 영향을 줍니다. 이전에는 스타일을 수정할 때 분명한 멈춤을 기다려야 했지만, 이제는 거의 수정 즉시 결과를 확인할 수 있습니다.

Oxide는 무엇을 제대로 해냈을까요?

Oxide 엔진의 핵심은 Rust + Lightning CSS입니다. Rust의 성능상 이점은 잘 알려져 있지만, 더 중요한 것은 아키텍처 차원의 변화입니다.

통합된 툴체인. v3 시절 Tailwind는 PostCSS 생태계에 의존했고 autoprefixer, cssnano 같은 도구를 추가로 설정해야 했습니다. v4는 이 기능을 모두 내장하고 Lightning CSS 패키지 하나에만 의존합니다. 중간 단계가 줄었으니 자연스럽게 더 빨라졌습니다.

지능형 콘텐츠 감지. 이전에는 tailwind.config.js의 content 배열에 Tailwind가 클래스 이름을 스캔할 파일을 직접 지정해야 했습니다. v4는 .gitignore와 모듈 그래프를 읽고 스캔해야 할 파일을 자동으로 찾아냅니다. 설정은 줄고 속도는 빨라졌습니다.

네이티브 CSS 기능. v4는 실제 @layer 규칙, @property 사용자 정의 속성, color-mix() 색상 함수 같은 현대적인 CSS 기능을 사용합니다. 브라우저가 기본적으로 지원하므로 빌드 단계에서 변환할 필요가 없습니다.

솔직히 이러한 기술 세부 사항을 모두 이해할 필요는 없습니다. 중요한 것은 결과입니다. 빌드는 빨라졌고, 설정은 줄었으며, 개발 경험은 좋아졌습니다.

CSS-first 설정 — tailwind.config.js와 작별하기

이는 v4에서 가장 큰 변화이자 마이그레이션 비용이 가장 많이 드는 부분입니다.

이전에는 tailwind.config.js에 설정을 작성했지만, 이제는 CSS 파일의 @theme 지시어로 옮겨야 합니다. 솔직히 처음에는 꽤 낯설었습니다. 몇 년 동안 JS 설정을 작성하다가 갑자기 CSS 변수를 쓰려니 어색했죠. 하지만 일정 기간 사용해 보니 오히려 CSS의 사고방식에 더 잘 맞았습니다.

설정 마이그레이션: Before & After

가장 간단한 예부터 살펴보겠습니다. 기본 색상을 사용자 정의해 보겠습니다.

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
    },
  },
}

v4에서는 이 설정이 모두 CSS로 들어갑니다.

/* v4: app.css */
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
}

변수 이름이 primary에서 --color-primary로 바뀐 것을 눈치챘을 것입니다. v4에는 엄격한 이름 접두사 규칙이 있기 때문입니다.

변수 이름 규칙 비교표

v3 설정 항목	v4 CSS 변수 접두사	예시
colors	—color-*	—color-primary: #3b82f6
spacing	—spacing-*	—spacing-128: 32rem
fontSize	—text-*	—text-xs: 0.75rem
fontFamily	—font-*	—font-sans: “Inter”
borderRadius	—radius-*	—radius-lg: 0.5rem
screens	—breakpoint-*	—breakpoint-md: 768px
boxShadow	—shadow-*	—shadow-card: 0 4px 12px rgba(0,0,0,0.1)
animation	—animate-*	—animate-spin: spin 1s linear infinite

처음에는 이 접두사 체계가 번거롭게 느껴질 수 있지만 장점도 있습니다. 변수 이름을 추측할 필요가 없습니다. 글꼴 크기 변수를 어떻게 작성하는지 궁금하다면, 반드시 --text-로 시작한다는 것을 알 수 있습니다.

더 복잡한 설정 예시

조금 더 완전한 예를 살펴보겠습니다. v3 설정이 다음과 같다고 가정해 보겠습니다.

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          light: '#f0f9ff',
          DEFAULT: '#0ea5e9',
          dark: '#0369a1',
        },
      },
      fontFamily: {
        display: ['Cal Sans', 'sans-serif'],
      },
      animation: {
        'fade-in': 'fadeIn 0.5s ease-out',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

v4로 마이그레이션하면 다음과 같습니다.

/* v4: app.css */
@import "tailwindcss";

@theme {
  /* 색상 */
  --color-brand-light: #f0f9ff;
  --color-brand: #0ea5e9;
  --color-brand-dark: #0369a1;

  /* 글꼴 */
  --font-display: "Cal Sans", sans-serif;

  /* 애니메이션 */
  --animate-fade-in: fadeIn 0.5s ease-out;
}

/* 플러그인 */
@plugin "@tailwindcss/typography";

몇 가지 변화에 주목하세요.

1. 색상 계층 구조를 펼칩니다. v3는 중첩 객체 brand.light를 지원하지만, v4에서는 --color-brand-light로 작성해야 합니다.
2. 플러그인은 @plugin으로 불러옵니다. 더 이상 JS에서 require할 필요가 없습니다.
3. DEFAULT 접미사가 사라졌습니다. brand의 기본 색상은 바로 --color-brand로 작성합니다.

다크 모드 설정

v3의 다크 모드 설정은 다음과 같습니다.

// v3
module.exports = {
  darkMode: 'class', // 또는 'media'
}

v4는 기본적으로 media 전략(시스템 설정 따르기)을 사용합니다. class로 바꾸려면 CSS에 다음 한 줄을 추가하세요.

/* v4 */
@import "tailwindcss";
@variant dark (&:where(.dark, .dark *));

이 코드는 요소 또는 상위 요소에 .dark 클래스가 있을 때 다크 모드 스타일을 적용한다는 뜻입니다.

콘텐츠 감지 설정

이전에는 스캔할 파일을 직접 지정해야 했습니다.

// v3
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './public/index.html',
  ],
}

v4는 .gitignore를 자동으로 읽고 제외된 파일을 무시한 뒤, 프로젝트의 모든 관련 파일을 스캔합니다. 프로젝트 구조가 특수하다면 @source로 직접 추가할 수 있습니다.

/* v4 */
@import "tailwindcss";
@source "../node_modules/my-ui-lib";

CSS-first 설정의 가장 큰 장점은 스타일과 관련된 설정이 모두 하나의 CSS 파일에 모인다는 점입니다. JS와 CSS 사이를 오갈 필요가 없습니다. 반면 JS 설정에 익숙한 개발자에게는 적응 기간이 필요하다는 단점도 있습니다.

설치 및 통합 — 설정이 거의 필요 없는 새로운 경험

Tailwind v3를 설치해 본 사람이라면 그 과정을 알고 있을 것입니다. 패키지 세 개를 설치하고, 설정 파일을 만들고, PostCSS를 구성하고, content 배열을 작성해야 했습니다. 복잡한 과정은 아니지만 새 프로젝트마다 반복해야 했습니다.

v4는 이 과정을 최대한 단순하게 만들었습니다.

가장 간단한 설치

Vite를 사용한다면 두 단계면 충분합니다.

# 1. 설치
npm install tailwindcss @tailwindcss/vite

# 2. vite.config.js에 한 줄 추가
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()],
}

그런 다음 CSS 파일에 import 한 줄을 추가합니다.

/* app.css 또는 index.css */
@import "tailwindcss";

이것으로 끝입니다. tailwind.config.js도, postcss.config.js도, content 배열도 없습니다. 바로 사용할 수 있습니다.

세 가지 통합 방식

Vite 통합(권장):

npm install tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()],
}

PostCSS 통합:

npm install tailwindcss @tailwindcss/postcss

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

CLI 사용:

npx tailwindcss -i input.css -o output.css --watch

대부분의 현대적인 프로젝트에는 Vite 통합이면 충분합니다. PostCSS 방식은 기존 프로젝트를 마이그레이션할 때 적합하고, CLI는 빌드 프로세스가 없는 환경에 적합합니다.

자동 콘텐츠 감지 원리

v4에서는 content 배열을 설정하지 않아도 필요한 파일을 자동으로 찾아냅니다. 어떻게 가능할까요?

.gitignore 파일을 읽어 스캔할 필요가 없는 디렉터리(node_modules, dist 등)를 제외한 다음, 나머지 파일에서 Tailwind 클래스 이름을 검색합니다.

이 메커니즘에는 한 가지 전제가 있습니다. 프로젝트가 표준 Node.js 프로젝트 구조여야 합니다. 템플릿 파일을 프로젝트 루트 밖의 폴더처럼 특이한 위치에 두었다면 직접 지정해야 합니다.

@import "tailwindcss";
@source "../templates";  /* 스캔 경로 직접 추가 */

자동 감지의 또 다른 장점은 새 파일을 만들 때 설정을 수정할 필요가 없다는 것입니다. 이전에는 새 컴포넌트 파일을 만들 때마다 tailwind.config.js의 content 배열을 업데이트해야 했습니다(**/* 와일드카드를 사용하면 필요 없지만 일부 프로젝트 구조에서는 지원되지 않습니다). 이제는 신경 쓸 필요 없이 새 파일에서 바로 사용할 수 있습니다.

주요 변경 사항과 마이그레이션 체크리스트

이 부분이 마이그레이션의 핵심입니다. 너무 걱정할 필요는 없습니다. 대부분의 변경 사항에는 일정한 규칙이 있고, 공식 자동 마이그레이션 도구도 제공됩니다.

투명도 수정자 변경

가장 큰 영향을 주는 변경 사항입니다. v3에서는 배경 투명도를 다음과 같이 설정했습니다.

<!-- v3 -->
<div class="bg-blue-500 bg-opacity-50">...</div>

v4는 투명도를 색상 값에 통합했습니다.

<!-- v4 -->
<div class="bg-blue-500/50">...</div>

배경색뿐만 아니라 색상과 관련된 모든 속성이 이 문법을 지원합니다.

<!-- 텍스트 색상 투명도 -->
<p class="text-gray-900/75">...</p>

<!-- 테두리 색상 투명도 -->
<div class="border-red-500/30">...</div>

그렇다면 bg-opacity-* 같은 클래스는 어떻게 해야 할까요? 삭제하면 됩니다. v4에서는 더 이상 지원하지 않습니다.

이름이 변경된 유틸리티 클래스

v4에서는 일부 유틸리티 클래스의 이름을 바꿨습니다. 주로 이름을 단순화하거나 의미를 조정한 변경입니다.

v3 클래스 이름	v4 클래스 이름	설명
flex-grow	grow	이름 단순화
flex-grow-*	grow-*	이름 단순화
flex-shrink	shrink	이름 단순화
flex-shrink-*	shrink-*	이름 단순화
overflow-ellipsis	text-ellipsis	분류 조정
decoration-slice	box-decoration-slice	분류 조정
shadow-sm	shadow-xs	크기 이름 변경
shadow	shadow-sm	크기 이름 변경
rounded-sm	rounded-xs	크기 이름 변경
rounded	rounded-sm	크기 이름 변경
outline-none	outline-hidden	의미 변경

shadow와 rounded의 변화에 주의하세요. 기존 shadow는 shadow-sm이 되었고, 기존 shadow-sm은 shadow-xs가 되었습니다. 크기 이름을 더 일관되게 만들기 위한 의미 조정입니다.

기본값 변경

일부 기본값이 바뀌었기 때문에 스타일이 달라질 수 있습니다.

border 기본 색상: v3에서는 gray-200이었지만 v4에서는 currentColor로 변경되었습니다. 즉, 테두리 색상이 텍스트 색상을 따릅니다.

<!-- v3: 테두리가 회색 -->
<div class="border text-blue-500">테두리는 gray-200</div>

<!-- v4: 테두리가 텍스트 색상을 따름 -->
<div class="border text-blue-500">테두리는 blue-500</div>

ring 기본값: v3의 기본 너비는 3px, 색상은 blue-500이었지만 v4에서는 너비 1px, 색상 currentColor로 변경되었습니다.

<!-- v3: ring은 파란색 3px -->
<button class="ring">...</button>

<!-- v4: ring은 currentColor 1px -->
<button class="ring">...</button>

<!-- v3 효과가 필요한 경우 -->
<button class="ring-3 ring-blue-500">...</button>

전체 마이그레이션 체크리스트

다음 순서대로 진행하세요.

1. 의존성 업그레이드

   npm install tailwindcss@latest @tailwindcss/vite@latest

2. 자동 마이그레이션 도구 실행

   npx @tailwindcss/upgrade

   이 도구는 @tailwind 지시어, 투명도 클래스 이름, 이름이 변경된 유틸리티 클래스 등 대부분의 문법을 자동으로 변환합니다.

3. CSS 엔트리 파일 변환

   /* v3 */
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   
   /* v4 */
   @import "tailwindcss";

4. 설정 파일 마이그레이션: tailwind.config.js의 설정을 CSS의 @theme 블록으로 옮깁니다.

5. 플러그인 업데이트: JS 플러그인을 @plugin 문법으로 바꿉니다.

   @plugin "@tailwindcss/typography";

6. 투명도 클래스 이름 확인: bg-opacity, text-opacity, border-opacity를 전체 검색하고 새로운 문법으로 바꿉니다.

7. 이름이 변경된 클래스 확인: 특히 shadow-*, rounded-*, flex-grow-*, flex-shrink-*를 확인합니다.

8. 기본값 변경 확인: border 색상과 ring 스타일을 특히 주의해서 살펴봅니다.

9. 시각적 회귀 테스트: 시각 테스트를 실행해 빠뜨린 변경 사항이 없는지 확인합니다.

자동 마이그레이션 도구는 작업의 80%를 처리할 수 있지만, 나머지 20%는 수동으로 확인해야 합니다. 특히 기본값 변경은 도구가 의도를 판단할 수 없으므로 직접 조정해야 합니다.

새로운 기능 — Container Queries, 3D Transforms 등 주요 기능

성능과 설정 개선 외에도 v4에는 실용적인 새로운 기능이 추가되었습니다.

Container Queries 기본 지원

이전에는 Container Queries를 사용하려면 플러그인을 설치해야 했지만, 이제 기본으로 지원합니다.

<!-- 컨테이너 정의 -->
<div class="@container">
  <!-- 컨테이너 너비에 따라 반응 -->
  <div class="@md:grid-cols-2 @lg:grid-cols-3">
    ...
  </div>
</div>

@container는 container-type: inline-size에 해당하며, @md:는 컨테이너 쿼리 브레이크포인트입니다. 반응형 브레이크포인트 md:와 문법이 비슷하지만 앞에 @가 붙습니다.

이는 컴포넌트 라이브러리에 특히 적합합니다. 컴포넌트 스타일이 화면 너비가 아니라 상위 컨테이너 너비에 따라 반응할 수 있기 때문입니다.

3D Transform 유틸리티 클래스

v4에는 3D 변환 유틸리티 세트가 추가되었습니다.

<!-- 3D 원근감 -->
<div class="perspective-distant">
  <!-- X축 회전 -->
  <div class="rotate-x-45">...</div>
</div>

<!-- Y축 회전 -->
<div class="rotate-y-12">...</div>

<!-- Z축 확대/축소 -->
<div class="scale-z-150">...</div>

사용 가능한 클래스에는 rotate-x-*, rotate-y-*, rotate-z-*, scale-z-*, perspective-*, translate-z-* 등이 있습니다. 카드 뒤집기 효과나 3D 메뉴 같은 인터랙션을 훨씬 쉽게 구현할 수 있습니다.

@starting-style 변형

CSS 네이티브 @starting-style 기능과 함께 사용하며, 요소가 처음 렌더링될 때의 스타일을 지정합니다.

<!-- 요소가 나타날 때 투명 상태에서 불투명 상태로 전환 -->
<div class="starting:opacity-0 opacity-100 transition-opacity">
  ...
</div>

JavaScript 없이도 진입 애니메이션을 구현할 수 있습니다. 이전에는 animate-fade-in 같은 사용자 정의 애니메이션이 필요했지만 이제는 클래스 한 줄이면 됩니다.

not-* 변형

CSS :not() 의사 클래스를 지원합니다.

<!-- 마지막 요소가 아닌 모든 자식 요소 -->
<li class="not-last:mb-4">...</li>

<!-- disabled 상태가 아닌 모든 버튼 -->
<button class="not-disabled:opacity-100">...</button>

이전에는 이런 요구 사항을 last:mb-0 같은 반대 방향으로 작성해야 했지만, 이제는 not-*를 사용해 더 직관적으로 표현할 수 있습니다.

확장된 Gradient API

v4에서는 그라데이션 기능도 강화되었습니다.

<!-- Conic 그라데이션 -->
<div class="bg-conic/from-red-500 via-yellow-500 to-blue-500">...</div>

<!-- 방사형 그라데이션 -->
<div class="bg-radial from-white to-transparent">...</div>

<!-- 그라데이션 보간 모드 -->
<div class="bg-linear-to-r from-blue-500 to-purple-500 via-oklch">...</div>

via-oklch는 새로운 보간 모드로, 특히 색 공간을 변환할 때 그라데이션 전환을 더 자연스럽게 만듭니다.

결론

그렇다면 업그레이드해야 할까요?

프로젝트가 아직 활발하게 개발 중이라면 업그레이드를 권합니다. HMR이 수백 밀리초에서 10여 밀리초로 줄어들면 매일 적지 않은 대기 시간을 절약할 수 있습니다. CSS 크기와 메모리 사용량까지 줄어들기 때문에 대규모 프로젝트일수록 이점이 큽니다.

마이그레이션 비용은 주로 설정 변환과 클래스 이름 변경에서 발생합니다. 다행히 자동 마이그레이션 도구 npx @tailwindcss/upgrade가 반복 작업의 대부분을 처리합니다. 직접 사용해 본 결과, 중간 규모 프로젝트(컴포넌트 200개 이상)는 테스트를 포함해 약 반나절이면 마이그레이션을 마칠 수 있었습니다.

새 프로젝트라면 바로 v4를 사용하세요. 간소화된 설치, 자동 콘텐츠 감지, CSS-first 설정 덕분에 Tailwind가 더 사용하기 편해졌습니다. 사용하지 않을 이유가 없습니다.

브라우저 호환성은 꼭 확인하세요. v4는 Safari 16.4+, Chrome 111+, Firefox 128+가 필요합니다. 구형 브라우저를 지원해야 하는 프로젝트라면 조금 더 기다리는 편이 좋습니다.

권장 작업:

• 새 프로젝트에서는 바로 v4 사용
• 기존 프로젝트에서는 npx @tailwindcss/upgrade로 자동 마이그레이션
• border 기본 색상과 ring 기본값 변경을 중점적으로 확인
• 문제가 생기면 공식 업그레이드 문서 확인