Tailwind CSS v4로 마이그레이션하기: CSS-first 설정의 모든 것

Tailwind CSS v4가 정식 출시되면서 가장 먼저 눈에 띄는 변화는 tailwind.config.js 파일이 사라졌다는 점입니다. 대신 CSS 파일 자체가 설정 파일이 됩니다.

@theme 디렉티브란?

@theme은 Tailwind v4에서 디자인 토큰을 정의하는 새로운 방법입니다. 기존에 theme.extend에 작성하던 내용을 CSS 파일 안에 직접 씁니다.

/* global.css */
@import "tailwindcss";

@theme {
  --color-primary: #3F4367;
  --color-surface: #131313;
  --font-family-display: 'Manrope', sans-serif;
}

이렇게 선언하면 bg-primary, text-surface, font-display 같은 유틸리티 클래스가 자동으로 생성됩니다.

CSS 변수와의 결합

v4의 진짜 강점은 CSS 커스텀 프로퍼티와의 자연스러운 결합입니다. 다크 모드 구현이 훨씬 직관적이 됩니다.

:root {
  --color-bg: #F7F8F8;
  --color-text: #1D2023;
}

.dark {
  --color-bg: #131313;
  --color-text: #E8E8F0;
}

@theme {
  --color-bg: var(--color-bg);
  --color-text: var(--color-text);
}

이제 JS로 html 요소에 .dark 클래스만 토글하면 모든 Tailwind 유틸리티가 자동으로 다크 모드로 전환됩니다.

마이그레이션 체크리스트

1. tailwind.config.js 삭제
2. @tailwind base/components/utilities → @import "tailwindcss"로 교체
3. theme.extend.* → @theme { } 블록으로 이동
4. theme.colors.* 커스텀 컬러 → CSS 변수로 선언 후 @theme에서 참조

주의할 점

v4에서는 Tailwind 빌트인 색상 팔레트가 기본으로 포함되지 않습니다. 필요한 경우 @import "tailwindcss/theme" 으로 명시적으로 불러와야 합니다. 저처럼 디자인 토큰을 직접 관리하는 경우에는 오히려 번들 사이즈가 줄어드는 이점이 있습니다.