Tailwind CSS v4 마이그레이션 가이드 — 새로운 엔진, 새로운 가능성

Tailwind CSS v4가 출시되었습니다. Oxide라는 새로운 Rust 기반 엔진을 탑재하고, JavaScript 설정 파일 대신 CSS 기반 설정으로 전환되었습니다. 이 가이드에서는 기존 프로젝트를 v4로 마이그레이션하는 방법을 다룹니다.

주요 변경 사항

1. Oxide 엔진

10배 빠른 빌드 속도
Rust로 재작성된 핵심 엔진
메모리 사용량 대폭 감소

2. CSS 기반 설정

/* v4: tailwind.config.js 대신 CSS에서 설정 */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
  --font-sans: 'Inter', sans-serif;
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
}

3. Native CSS 기능 활용

CSS 변수 네이티브 지원
@layer 표준 사용
light-dark() 함수 지원

마이그레이션 준비

호환성 체크

# Node.js 18.0 이상 필요
node --version

# 현재 Tailwind 버전 확인
npm list tailwindcss

백업

# 설정 파일 백업
cp tailwind.config.js tailwind.config.js.backup
cp postcss.config.js postcss.config.js.backup

자동 마이그레이션

공식 마이그레이션 도구 사용

# 자동 마이그레이션 실행
npx @tailwindcss/upgrade@latest

# 또는 수동으로 업그레이드
npm install tailwindcss@latest

마이그레이션 도구가 수행하는 작업:

tailwind.config.js → CSS @theme 변환
더 이상 사용되지 않는 클래스 업데이트
PostCSS 설정 업데이트

수동 마이그레이션

1. 패키지 업데이트

npm install tailwindcss@4 @tailwindcss/postcss@4 @tailwindcss/cli@4
npm uninstall autoprefixer # v4에 내장됨

2. PostCSS 설정 변경

// postcss.config.js (v3)
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// postcss.config.js (v4)
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

3. CSS 파일 업데이트

/* v3 방식 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 방식 */
@import "tailwindcss";

4. 설정 마이그레이션

v3 tailwind.config.js:

module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        secondary: '#10b981',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
      spacing: {
        '128': '32rem',
      },
    },
  },
  plugins: [],
};

v4 CSS 설정:

@import "tailwindcss";

@theme {
  /* 색상 */
  --color-primary: #3b82f6;
  --color-secondary: #10b981;

  /* 폰트 */
  --font-sans: 'Inter', sans-serif;

  /* 커스텀 스페이싱 */
  --spacing-128: 32rem;
}

/* content 경로는 자동 감지 (설정 불필요) */

클래스 변경 사항

그라데이션

<!-- v3 -->
<div class="bg-gradient-to-r from-blue-500 to-purple-500">

<!-- v4: 동일하게 동작 -->
<div class="bg-gradient-to-r from-blue-500 to-purple-500">

<!-- v4 새 기능: 그라데이션 위치 -->
<div class="bg-gradient-to-r from-blue-500 from-20% to-purple-500 to-80%">

컨테이너

<!-- v3 -->
<div class="container mx-auto px-4">

<!-- v4: @container 네이티브 지원 -->
<div class="@container">
  <div class="@md:flex @lg:grid">

다크 모드

/* v4: light-dark() 네이티브 함수 사용 */
@theme {
  --color-bg: light-dark(#ffffff, #0f172a);
  --color-text: light-dark(#1e293b, #f1f5f9);
}

<!-- 사용 -->
<div class="bg-[--color-bg] text-[--color-text]">

새로운 기능

1. 동적 유틸리티

<!-- 임의의 값 사용 간소화 -->
<div class="p-[calc(theme(spacing.4)+1px)]">

<!-- v4: CSS 변수 직접 참조 -->
<div class="p-[--custom-padding]">

2. 컨테이너 쿼리 네이티브

<div class="@container">
  <div class="@sm:flex @md:grid @lg:hidden">
    컨테이너 크기에 따라 변경
  </div>
</div>

3. 새로운 변형

<!-- 그룹 내 상태 -->
<div class="group">
  <button class="group-has-[:checked]:bg-blue-500">
</div>

<!-- 부모 상태 참조 -->
<div class="has-[:focus]:ring-2">
  <input type="text" />
</div>

<!-- 자식 존재 여부 -->
<div class="empty:hidden">
  <!-- 자식이 없으면 숨김 -->
</div>

4. 3D 변환

<div class="rotate-x-45 rotate-y-30 perspective-500">
  3D 변환
</div>

플러그인 마이그레이션

v3 플러그인

// v3 plugin
const plugin = require('tailwindcss/plugin');

module.exports = plugin(function({ addUtilities }) {
  addUtilities({
    '.text-shadow': {
      textShadow: '2px 2px 4px rgba(0,0,0,0.1)',
    },
  });
});

v4 방식

/* v4: CSS에서 직접 정의 */
@utility text-shadow {
  text-shadow: 2px 2px 4px rgba(0,0,0,0.1);
}

/* 변형 지원 */
@utility text-shadow-* {
  text-shadow: 2px 2px calc(var(--value) * 1px) rgba(0,0,0,0.1);
}

공식 플러그인

# v4 호환 버전으로 업데이트
npm install @tailwindcss/typography@latest
npm install @tailwindcss/forms@latest
npm install @tailwindcss/aspect-ratio@latest

/* CSS에서 import */
@import "tailwindcss";
@import "@tailwindcss/typography";
@import "@tailwindcss/forms";

트러블슈팅

빌드 에러

# 캐시 클리어
rm -rf node_modules/.cache
rm -rf .next/cache  # Next.js

# 재설치
rm -rf node_modules
npm install

스타일 적용 안됨

/* content 경로가 자동 감지 안 되는 경우 */
@import "tailwindcss" source("./src/**/*.{js,jsx,ts,tsx}");

CSS 변수 충돌

/* 기존 CSS 변수와 충돌 시 */
@theme prefix(tw) {
  --color-primary: #3b82f6;
}

/* 사용: tw-color-primary */

성능 비교

항목	v3	v4
초기 빌드	2.5s	0.2s
HMR	150ms	15ms
번들 크기	기준	-20%
CSS 파싱	Node.js	Rust

마이그레이션 체크리스트

Tailwind CSS v4는 성능과 개발 경험 모두에서 큰 개선을 가져왔습니다. CSS 네이티브 기능을 적극 활용하면서도 Tailwind의 편리함은 그대로 유지합니다. 마이그레이션에 시간을 투자할 가치가 충분합니다.