TailwindCSS v3 → v4 마이그레이션 실전 메모

[예시 글] 실제 마이그레이션 과정에서 겪은 내용을 기반으로 작성했어요.

가장 큰 변화: CSS-first

v4에서 tailwind.config.js가 사라지고 CSS 파일에서 직접 토큰을 정의해요:

@import "tailwindcss";
 
@theme {
  --color-brand: oklch(0.66 0.12 145);
  --font-pretendard: 'Pretendard Variable', sans-serif;
  --radius-card: 10px;
}

@theme 안에 정의한 CSS 변수는 자동으로 Tailwind 유틸리티 클래스가 생겨요. bg-brand, font-pretendard, rounded-card 처럼요.

oklch 색상 시스템

v4는 oklch를 포함한 최신 CSS 색상 함수를 완전히 지원해요. 기존 hex나 rgb보다 퍼셉추얼리 균일한 색상 팔레트를 만들 수 있어요:

/* 채도(chroma)만 바꾸면 같은 색상 계열 유지 */
--color-accent-subtle: oklch(0.94 0.04 145);
--color-accent:        oklch(0.66 0.12 145);
--color-accent-strong: oklch(0.45 0.16 145);

주의사항: PostCSS 설정

v4는 PostCSS 플러그인 방식이 바뀌었어요. tailwindcss/postcss를 씁니다:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

마이그레이션 결과

프로덕션 번들에서 사용하지 않는 클래스가 더 잘 제거됐어요. 기존 대비 CSS 파일 크기가 약 15% 줄었어요 (이 프로젝트 기준 — 환경에 따라 다를 수 있어요).