TailwindCSS v4 주요 변경점과 마이그레이션 완전 가이드

TailwindCSS v4가 정식 출시되면서 프런트엔드 생태계에 큰 변화가 찾아왔습니다. CSS-first 설정 방식, 새로운 유틸리티 클래스, 빌드 성능 개선 등 v3와 달라진 점이 많아 기존 프로젝트를 마이그레이션할 때 주의해야 할 부분이 있습니다. 이 글에서는 TailwindCSS v4의 핵심 변경점을 정리하고, v3에서 v4로 실전 마이그레이션하는 방법을 단계별로 안내합니다.

TailwindCSS v4의 핵심 변경점

TailwindCSS v4의 가장 큰 변화는 CSS-first 설정 방식의 도입입니다. 기존 v3에서는 tailwind.config.js 파일에서 JavaScript로 설정을 관리했지만, v4부터는 CSS 파일 내에서 직접 설정을 정의합니다. 이로 인해 설정 파일이 간소화되고, CSS 레이어를 더 직관적으로 제어할 수 있습니다.

1. CSS-first 설정 방식

v4에서는 @import "tailwindcss" 한 줄로 시작하고, CSS 파일 내에서 @theme 블록으로 디자인 토큰을 정의합니다. JavaScript 설정 파일 없이도 완전한 커스터마이징이 가능합니다.

/* v3 방식 (tailwind.config.js) */
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          500: '#06b6d4',
          600: '#0891b2',
        },
      },
      fontFamily: {
        sans: ['Pretendard', 'sans-serif'],
      },
    },
  },
}

/* v4 방식 (app.css) */
@import "tailwindcss";

@theme {
  --color-brand-500: #06b6d4;
  --color-brand-600: #0891b2;
  --font-sans: 'Pretendard', sans-serif;
}

2. 새로운 유틸리티 클래스와 문법

v4에서는 여러 유틸리티 클래스가 추가되고 일부 문법이 변경되었습니다. 대표적으로 shadow-sm이 shadow-xs로, blur-sm이 blur-xs로 변경되었습니다. 또한 ring 유틸리티의 기본 너비가 3px에서 1px로 바뀌었으니 마이그레이션 시 주의가 필요합니다.

그 외에도 그라디언트 방향 지정이 더 직관적으로 개선되었고, 컨테이너 쿼리가 기본 내장되어 플러그인 없이도 사용할 수 있습니다.

v3에서 v4 마이그레이션 단계별 가이드

Step 1. 패키지 업그레이드

먼저 TailwindCSS와 관련 패키지를 v4로 업그레이드합니다. v4부터는 PostCSS 플러그인 대신 Vite 플러그인 방식을 권장합니다.

# npm 사용 시
npm install tailwindcss@next @tailwindcss/vite@next

# 또는 pnpm
pnpm add tailwindcss@next @tailwindcss/vite@next

# vite.config.ts 설정
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

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

# app.css (PostCSS 방식 대신 직접 import)
@import "tailwindcss";

Step 2. 설정 파일 변환

기존 tailwind.config.js의 내용을 CSS @theme 블록으로 옮깁니다. 공식 마이그레이션 도구(npx @tailwindcss/upgrade)를 활용하면 대부분의 변환을 자동으로 처리할 수 있습니다.

# 공식 마이그레이션 도구 실행
npx @tailwindcss/upgrade

# 변환 전 (tailwind.config.js)
module.exports = {
  content: ['./src/**/*.{html,svelte,ts}'],
  theme: {
    extend: {
      colors: {
        primary: { 500: '#3b82f6' },
        gray: { 50: '#f9fafb' },
      },
      spacing: {
        18: '4.5rem',
        22: '5.5rem',
      },
    },
  },
}

# 변환 후 (app.css)
@import "tailwindcss";

@theme {
  --color-primary-500: #3b82f6;
  --color-gray-50: #f9fafb;
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
}

Step 3. 브레이킹 체인지 수정

자동 마이그레이션 도구로 처리되지 않는 항목들은 수동으로 수정해야 합니다. 주요 브레이킹 체인지 목록은 다음과 같습니다.

• shadow-sm → shadow-xs: 가장 작은 그림자 클래스명 변경
• ring → ring-1 또는 ring-3: 기본 ring 너비가 1px로 변경
• blur-sm → blur-xs: 블러 크기 클래스명 변경
• divide-*: 일부 divide 유틸리티 동작 방식 변경
• @apply 제한: @apply 내에서 변형자(modifier) 사용 방식 변경

SvelteKit 프로젝트 실전 마이그레이션 예시

SvelteKit + TailwindCSS v3 프로젝트를 v4로 마이그레이션한 실전 예시입니다. @tailwindcss/vite 플러그인을 활용해 설정을 최소화할 수 있습니다.

/* app.css — v4 스타일 설정 */
@import "tailwindcss";

@theme {
  /* 브랜드 컬러 */
  --color-brand-50: #ecfeff;
  --color-brand-500: #06b6d4;
  --color-brand-900: #164e63;

  /* 폰트 */
  --font-sans: 'Pretendard Variable', 'Pretendard', -apple-system, sans-serif;

  /* 커스텀 간격 */
  --spacing-18: 4.5rem;
}

/* 커스텀 레이어 */
@layer components {
  .btn-primary {
    @apply bg-brand-500 text-white px-4 py-2 rounded-lg font-medium
           hover:bg-brand-600 transition-colors duration-200;
  }

  .card {
    @apply bg-white rounded-xl shadow-sm border border-gray-100 p-6;
  }
}

/* SvelteKit 전역 스타일 */
@layer base {
  html {
    @apply scroll-smooth;
  }
  body {
    @apply font-sans text-gray-900 antialiased;
  }
}

빌드 성능 개선 확인하기

TailwindCSS v4는 Rust 기반 엔진으로 재작성되어 빌드 속도가 v3 대비 최대 10배 이상 빠릅니다. 특히 대형 프로젝트에서 개발 서버 재시작 시간과 핫 리로드 속도가 크게 개선됩니다. 마이그레이션 후 다음 명령으로 빌드 성능을 비교해 보세요.

# 빌드 시간 측정
time npm run build

# v3 평균 빌드 시간 (대형 프로젝트 기준)
# real    0m12.543s

# v4 평균 빌드 시간 (동일 프로젝트)
# real    0m1.238s

# 개발 서버 HMR 반응 시간
# v3: ~800ms ~ 1.2s
# v4: ~80ms ~ 150ms

마이그레이션 체크리스트

마이그레이션을 완료하기 전 다음 체크리스트를 확인하세요.

• ✅ @tailwindcss/vite 설치 및 vite.config 설정 완료
• ✅ CSS 파일에 @import "tailwindcss" 추가
• ✅ tailwind.config.js 내용을 @theme 블록으로 이전
• ✅ shadow-sm → shadow-xs 등 브레이킹 클래스 수정
• ✅ ring 클래스 기본값 변경 확인
• ✅ 플러그인 v4 호환 여부 확인 (@tailwindcss/typography 등)
• ✅ 빌드 및 E2E 테스트 통과 확인

코드벤터는 SvelteKit, FastAPI 등 최신 기술 스택을 활용한 웹 서비스 개발 경험을 바탕으로, 글로벌 협력 네트워크와 함께 다양한 프로젝트를 성공적으로 이끌어왔습니다. TailwindCSS v4 마이그레이션처럼 프레임워크 버전업이 필요하거나, 신규 서비스 기획부터 배포까지 전 과정이 필요하신 경우 코드벤터와 함께하세요.