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

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

# 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

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

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

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

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

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

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

@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]">

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

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

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

<!-- 그룹 내 상태 -->
<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>

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

// 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: 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 변수와 충돌 시 */
@theme prefix(tw) {
  --color-primary: #3b82f6;
}

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