Tailwind CSS v4 마이그레이션 완전 가이드 2026

Tailwind CSS v4란

Tailwind CSS v4는 2025년 초 출시된 메이저 버전으로, CSS-first 접근 방식으로의 전환이 핵심입니다. 설정을 JavaScript 파일이 아닌 CSS 파일에서 직접 관리합니다.

기존 v3 프로젝트를 유지보수하거나 새 프로젝트를 시작할 때 v4를 도입하는 방법을 단계별로 정리했습니다.

---

v3 vs v4 주요 변경점

---

마이그레이션 체크리스트

1단계: 자동 마이그레이션 시도

npx @tailwindcss/upgrade

자동 도구가 처리하는 항목:

• CSS 임포트 구문 변환
• PostCSS 설정 업데이트
• 삭제된 유틸리티 대체 클래스 적용
• 기본 테마 변수 이전

실행 전 반드시 Git 커밋 후 진행하세요.

2단계: 의존성 업데이트

# v3 관련 패키지 제거
npm uninstall tailwindcss postcss autoprefixer

# v4 패키지 설치
npm install tailwindcss@latest @tailwindcss/postcss

3단계: PostCSS 설정 변경

// postcss.config.mjs (v4)
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

v3에서 사용하던 autoprefixer는 v4에서 불필요합니다. @tailwindcss/postcss가 내장 처리합니다.

4단계: CSS 임포트 변경

/* Before (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After (v4) */
@import "tailwindcss";

5단계: 테마 마이그레이션

v3의 tailwind.config.js 테마를 CSS @theme으로 이전합니다.

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#2563eb',
        'brand-dark': '#1d4ed8',
      },
      fontFamily: {
        sans: ['Pretendard', 'sans-serif'],
      },
      spacing: {
        '128': '32rem',
      },
    },
  },
};

/* After: globals.css (v4) */
@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
  --color-brand-dark: #1d4ed8;
  --font-sans: 'Pretendard', sans-serif;
  --spacing-128: 32rem;
}

이제 bg-brand, text-brand-dark, font-sans 같은 유틸리티가 자동 생성됩니다.

---

다크 모드 마이그레이션

v4에서 다크 모드 설정 방식이 변경되었습니다.

// Before (v3): tailwind.config.js
module.exports = {
  darkMode: 'class',
};

/* After (v4): globals.css */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

또는 미디어 쿼리 기반 다크 모드:

@variant dark (&:where(@media (prefers-color-scheme: dark)));

HTML에서 사용 방법은 동일합니다:

<div class="bg-white dark:bg-gray-900">
  <p class="text-gray-900 dark:text-white">콘텐츠</p>
</div>

---

컨테이너 쿼리 (v4 신규 기능)

v3에서는 @tailwindcss/container-queries 플러그인이 필요했지만, v4에서는 기본 내장입니다.

<!-- v4: 컨테이너 쿼리 -->
<div class="@container">
  <div class="grid grid-cols-1 @md:grid-cols-2 @lg:grid-cols-3">
    <!-- 컨테이너 크기에 따라 반응 -->
  </div>
</div>

---

삭제·변경된 유틸리티 처리

불투명도 유틸리티 변경

<!-- Before (v3) -->
<div class="bg-black bg-opacity-50">
<p class="text-white text-opacity-75">

<!-- After (v4) — 슬래시 구문 -->
<div class="bg-black/50">
<p class="text-white/75">

슬래시 구문은 v3에서도 이미 지원되었으므로 기존 코드가 v3 스타일이라면 대부분 그대로 동작합니다.

ring-offset 변경

<!-- Before (v3) -->
<button class="ring-2 ring-blue-500 ring-offset-2 ring-offset-white">

<!-- After (v4) — outline 활용 권장 -->
<button class="outline-2 outline-blue-500 outline-offset-2">

제거된 divide-* 일부 유틸리티

divide-opacity-* 계열은 슬래시 구문으로 대체됩니다.

---

플러그인 마이그레이션

@tailwindcss/typography

npm install @tailwindcss/typography

/* globals.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

@tailwindcss/forms

npm install @tailwindcss/forms

@import "tailwindcss";
@plugin "@tailwindcss/forms";

v3에서 tailwind.config.js 플러그인 배열에 추가하던 방식 대신, CSS @plugin으로 임포트합니다.

---

Next.js + Tailwind v4 설정

# 새 프로젝트 (자동으로 v4 설정)
npx create-next-app@latest

# 기존 프로젝트 마이그레이션
npx @tailwindcss/upgrade

app/globals.css 기본 설정:

@import "tailwindcss";

@theme {
  /* 프로젝트 커스텀 토큰 */
  --color-primary: #2563eb;
  --font-sans: 'Pretendard Variable', sans-serif;
}

postcss.config.mjs:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

---

자주 발생하는 오류 해결

오류: "Unknown at-rule @tailwind"

원인: 구버전 PostCSS 플러그인 사용 중
해결: tailwindcss → @tailwindcss/postcss로 교체

오류: 커스텀 색상이 적용 안 됨

/* 잘못된 방법 */
@theme {
  --color-brand: hsl(221 83% 53%); /* 일부 함수 형식 미지원 */
}

/* 올바른 방법 */
@theme {
  --color-brand: #2563eb;
}

오류: 동적 클래스가 빌드 결과에 없음

v4도 동적 클래스 생성(문자열 연결)은 지원하지 않습니다.

// 잘못된 방법 — 빌드 시 제거됨
const color = 'blue';
<div className={`bg-${color}-500`}>

// 올바른 방법 — 전체 클래스명 사용
const colorClass = 'bg-blue-500';
<div className={colorClass}>

경고: Node 버전 불일치

Tailwind v4는 Node.js 18+ 필요합니다. .nvmrc 또는 engines 필드를 확인하세요.

---

v4 도입 시 성능 개선 체감 포인트

---

마이그레이션 우선순위 결정

---

v4 마이그레이션의 핵심은 설정이 CSS로 이동한다는 것입니다. 처음엔 낯설지만 익숙해지면 JS 설정보다 직관적입니다. 자동 도구로 먼저 시도하고, 실패한 부분만 수동으로 처리하는 접근이 효율적입니다.

관련 글: Next.js SSG 완전 가이드 · VS Code 생산성 확장