Tailwind CSS v4: 실제로 무엇이 바뀌었고 마이그레이션해야 할까 | Akousa

2026년 1월 9일16분 읽기

Tailwind CSS v4: 실제로 무엇이 바뀌었고 마이그레이션해야 할까

CSS 우선 설정, @layer 통합, 내장 컨테이너 쿼리, 새로운 엔진 성능, 브레이킹 체인지, v3에서 v4로의 솔직한 마이그레이션 경험.

Tailwind CSS를 v1.x 시절부터 사용해 왔습니다. 커뮤니티의 절반은 끔찍하다고 생각하고 나머지 절반은 멈추지 않고 제품을 출시하던 때였죠. 모든 메이저 버전이 상당한 도약이었지만, v4는 다릅니다. 단순한 기능 릴리스가 아닙니다. 프레임워크와의 근본적인 계약을 바꾸는 완전한 아키텍처 재작성입니다.

두 개의 프로덕션 프로젝트를 v3에서 v4로 마이그레이션하고 세 개의 새 프로젝트를 v4로 처음부터 시작한 후, 진정으로 나아진 점, 거친 부분, 그리고 지금 마이그레이션해야 하는지에 대한 명확한 그림을 갖게 되었습니다. 과대광고도 분노도 없이 — 제가 관찰한 것만 전합니다.

큰 그림: v4가 실제로 무엇인가

Tailwind CSS v4는 세 가지를 동시에 담고 있습니다:

새로운 엔진 — JavaScript에서 Rust(Oxide 엔진)로 재작성되어 빌드가 극적으로 빨라졌습니다
새로운 설정 패러다임 — CSS 우선 설정이 기본값으로 tailwind.config.js를 대체합니다
CSS 플랫폼과의 더 긴밀한 통합 — 네이티브 @layer, 컨테이너 쿼리, @starting-style, 캐스케이드 레이어가 일급 시민입니다

어디서나 보게 될 헤드라인은 "10배 빠름"입니다. 실제로 맞지만, 진짜 변화를 과소평가합니다. Tailwind를 설정하고 확장하는 멘탈 모델이 근본적으로 바뀌었습니다. 이제 CSS를 생성하는 JavaScript 설정 객체가 아니라 CSS 자체로 작업합니다.

최소한의 Tailwind v4 설정은 다음과 같습니다:

css

// v3 — tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: "#eff6ff",
          500: "#3b82f6",
          900: "#1e3a5f",
        },
      },
      fontFamily: {
        display: ["Inter Variable", "sans-serif"],
      },
      spacing: {
        18: "4.5rem",
        112: "28rem",
      },
      borderRadius: {
        "4xl": "2rem",
      },
    },
  },
};

css

@import "tailwindcss";
 
@theme {
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a5f;
 
  --font-display: "Inter Variable", sans-serif;
 
  --spacing-18: 4.5rem;
  --spacing-112: 28rem;
 
  --radius-4xl: 2rem;
}

css

@import "tailwindcss";
 
@theme {
  /* 먼저 모든 기본 색상을 초기화 */
  --color-*: initial;
 
  /* 이제 자신의 색상만 정의 */
  --color-white: #ffffff;
  --color-black: #000000;
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a5f;
}

css

/* styles/theme/colors.css */
@theme {
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-200: #bfdbfe;
  --color-brand-300: #93c5fd;
  --color-brand-400: #60a5fa;
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
  --color-brand-800: #1e40af;
  --color-brand-900: #1e3a5f;
  --color-brand-950: #172554;
}
 
/* styles/theme/typography.css */
@theme {
  --font-display: "Inter Variable", sans-serif;
  --font-body: "Source Sans 3 Variable", sans-serif;
  --font-mono: "JetBrains Mono Variable", monospace;
 
  --text-display: 3.5rem;
  --text-display--line-height: 1.1;
  --text-display--letter-spacing: -0.02em;
}

css

/* v4 출력 — 간소화 */
@layer theme, base, components, utilities;
 
@layer base {
  /* 리셋, preflight */
}
 
@layer components {
  /* 컴포넌트 클래스 */
}
 
@layer utilities {
  /* 모든 생성된 유틸리티 클래스 */
}

css

@layer components {
  /* 구체성: 0-1-0 */
  .card {
    padding: 1rem;
  }
}
 
@layer utilities {
  /* 구체성: 0-1-0 — 같은 구체성이지만 utilities 레이어가 나중이므로 승리 */
  .p-4 {
    padding: 1rem;
  }
}

// v3 — 플러그인 접근 방식
const plugin = require("tailwindcss/plugin");
 
module.exports = {
  plugins: [
    plugin(function ({ addUtilities }) {
      addUtilities({
        ".text-balance": {
          "text-wrap": "balance",
        },
        ".text-pretty": {
          "text-wrap": "pretty",
        },
      });
    }),
  ],
};

html

<!-- 부모를 컨테이너로 표시 -->
<div class="@container">
  <!-- 뷰포트가 아닌 부모의 너비에 반응 -->
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3">
    <div class="p-4">카드 1</div>
    <div class="p-4">카드 2</div>
    <div class="p-4">카드 3</div>
  </div>
</div>

html

<div class="@container/sidebar">
  <div class="@container/card">
    <!-- card 컨테이너를 쿼리 -->
    <div class="@md/card:text-lg">...</div>
 
    <!-- sidebar 컨테이너를 쿼리 -->
    <div class="@lg/sidebar:hidden">...</div>
  </div>
</div>

html

<!-- 이 컴포넌트는 배치된 모든 컨테이너에 적응합니다 -->
<article class="@container">
  <div class="grid grid-cols-1 @md:grid-cols-[200px_1fr] gap-4">
    <img
      class="w-full @md:w-auto rounded-lg aspect-video @md:aspect-square object-cover"
      src="/post-image.jpg"
      alt=""
    />
    <div>
      <h2 class="text-lg @lg:text-xl font-semibold">게시글 제목</h2>
      <p class="mt-2 text-sm @md:text-base text-gray-600">게시글 발췌 내용이 여기에 들어갑니다...</p>
      <div class="mt-4 hidden @md:flex gap-2">
        <span class="text-xs bg-gray-100 px-2 py-1 rounded">태그</span>
      </div>
    </div>
  </div>
</article>

html

<!-- 마지막을 제외한 모든 자식에 테두리 적용 -->
<div class="divide-y">
  <div class="not-last:pb-4">항목 1</div>
  <div class="not-last:pb-4">항목 2</div>
  <div class="not-last:pb-4">항목 3</div>
</div>
 
<!-- 비활성화되지 않은 모든 것에 스타일 적용 -->
<input class="not-disabled:hover:border-brand-500" />
 
<!-- data 속성 부정 -->
<div class="not-data-active:opacity-50">...</div>

html

<ul>
  <li class="nth-1:font-bold">첫 번째 항목 — 굵게</li>
  <li class="nth-even:bg-gray-50">짝수 행 — 회색 배경</li>
  <li class="nth-odd:bg-white">홀수 행 — 흰색 배경</li>
  <li class="nth-[3n+1]:text-brand-500">3번째+1마다 — 브랜드 색상</li>
</ul>

html

<!-- 이 div 안의 모든 단락, 모든 깊이에서 -->
<div class="**:data-highlight:bg-yellow-100">
  <section>
    <p data-highlight>이것이 강조됩니다</p>
    <div>
      <p data-highlight>이것도, 더 깊이 중첩되어도</p>
    </div>
  </section>
</div>

/* v4에서 제거됨 */
bg-opacity-*     → bg-black/50 사용 (슬래시 불투명도 구문)
text-opacity-*   → text-black/50 사용
border-opacity-* → border-black/50 사용
flex-shrink-*    → shrink-* 사용
flex-grow-*      → grow-* 사용
overflow-ellipsis → text-ellipsis 사용
decoration-slice  → box-decoration-slice 사용
decoration-clone  → box-decoration-clone 사용

// v3 플러그인
plugin(function ({ addUtilities, theme }) {
  addUtilities({
    ".scrollbar-hide": {
      "-ms-overflow-style": "none",
      "scrollbar-width": "none",
      "&::-webkit-scrollbar": {
        display: "none",
      },
    },
  });
});

// v3 설정 — 이전
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          light: "#60a5fa",
          DEFAULT: "#3b82f6",
          dark: "#1d4ed8",
        },
      },
      fontSize: {
        "2xs": ["0.65rem", { lineHeight: "1rem" }],
      },
      animation: {
        "fade-in": "fade-in 0.5s ease-out",
      },
      keyframes: {
        "fade-in": {
          "0%": { opacity: "0" },
          "100%": { opacity: "1" },
        },
      },
    },
  },
};

css

/* v4 CSS — 이후 */
@import "tailwindcss";
 
@theme {
  --color-brand-light: #60a5fa;
  --color-brand: #3b82f6;
  --color-brand-dark: #1d4ed8;
 
  --text-2xs: 0.65rem;
  --text-2xs--line-height: 1rem;
 
  --animate-fade-in: fade-in 0.5s ease-out;
}
 
@keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

json

{
  "@tailwindcss/typography": "^1.0.0",
  "@tailwindcss/forms": "^1.0.0",
  "@tailwindcss/container-queries": "제거 — 이제 내장됨",
  "tailwindcss-animate": "v4 지원 확인",
  "prettier-plugin-tailwindcss": "최신으로 업데이트"
}

css

/* data attribute 접근 방식 */
@variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
 
/* 미디어 쿼리 — 이것이 기본값이므로 선언할 필요 없음 */
@variant dark (@media (prefers-color-scheme: dark));

css

@import "tailwindcss";
 
@theme {
  --color-brand: var(--brand-primary, #3b82f6);
  --color-brand-light: var(--brand-light, #60a5fa);
  --color-brand-dark: var(--brand-dark, #1d4ed8);
}
 
/* 브랜드 오버라이드 */
.theme-acme {
  --brand-primary: #e11d48;
  --brand-light: #fb7185;
  --brand-dark: #9f1239;
}
 
.theme-globex {
  --brand-primary: #059669;
  --brand-light: #34d399;
  --brand-dark: #047857;
}

지표	v3 (Node)	v4 (Oxide)	개선
초기 빌드	4,280ms	387ms	11배
증분(파일 1개 편집)	340ms	18ms	19배
전체 재빌드(클린)	5,100ms	510ms	10배
개발 서버 시작	3,200ms	290ms	11배

변형	최소 너비
`@sm`	24rem (384px)
`@md`	28rem (448px)
`@lg`	32rem (512px)
`@xl`	36rem (576px)
`@2xl`	42rem (672px)

설정	v3 + Webpack	v3 + Turbopack	v4 + Turbopack
콜드 스타트	4.8s	2.1s	1.3s
HMR (CSS 변경)	450ms	180ms	40ms

지표	v3	v4
피크 메모리 (빌드)	380MB	45MB
정상 상태 (개발)	210MB	28MB

큰 그림: v4가 실제로 무엇인가

@theme을 사용한 CSS 우선 설정

기본 테마 재정의 vs 확장

다중 테마 파일

Oxide 엔진: 실제로 10배 빠릅니다

왜 이렇게 빠른가?

속도가 정말 중요한가?

네이티브 @layer 통합

커스텀 유틸리티 추가

커스텀 변형

컨테이너 쿼리: 내장, 플러그인 불필요

기본 사용법

이름 있는 컨테이너

왜 이것이 중요한가

실제로 중요한 새로운 변형

starting: 변형

not-* 변형

nth-* 변형

in-* 변형 (부모 상태)

**: 깊은 범용 변형

브레이킹 체인지: 실제로 무엇이 깨졌나

1. 설정 형식

2. 제거된 사용 중단 유틸리티

3. 기본 색상 팔레트 변경

4. 콘텐츠 감지

5. 플러그인 API 변경

6. JIT가 유일한 모드

7. 일부 변형 구문 변경

마이그레이션 가이드: 실제 프로세스

1단계: 공식 코드모드 실행

코드모드가 잘 처리하는 것

코드모드가 처리하지 못하는 것

2단계: PostCSS 설정 수정

3단계: 테마 설정 변환

4단계: 시각적 회귀 테스트

5단계: 서드파티 의존성 업데이트

Next.js와 함께 사용하기

PostCSS 접근 방식 (Next.js에 권장)

CSS 임포트 순서

다크 모드

Turbopack 호환성

성능 심층 분석: 빌드 속도를 넘어서

메모리 사용량

CSS 출력 크기

테마 값의 트리 셰이킹

고급: 멀티 브랜드를 위한 테마 구성

v3에서 그리운 것들

마이그레이션해야 할까?

지금 마이그레이션할 경우:

기다릴 경우:

마이그레이션하지 말 경우:

솔직한 의견

관련 게시물

Regex Cheat Sheet 2026 — Regular Expressions Made Simple

How to Compress Images Without Losing Quality: The Complete 2026 Guide

`starting:` 변형

`not-*` 변형

`nth-*` 변형

`in-*` 변형 (부모 상태)

`**:` 깊은 범용 변형