Tailwind CSS v4 마이그레이션 완벽 가이드 — CSS-first 설정으로의 전환

Tailwind CSS v4 CSS-first 설정 방식

v4에서 가장 큰 변화는 설정을 JavaScript 파일 대신 CSS 파일에서 직접 정의하는 CSS-first 접근 방식이다. tailwind.config.js는 더 이상 존재하지 않으며, CSS 파일에서 @import "tailwindcss"로 가져오고 @theme 블록에서 커스텀 디자인 토큰을 선언한다. 이 변경으로 빌드 파이프라인에서 JS 설정 파일 처리가 사라지고, CSS 변수 기반 테마가 런타임에서도 동적으로 적용 가능해진다. 에디터에서 CSS 파일의 @theme 블록을 수정하면 즉시 반영되어 개발 경험이 향상된다.

/* globals.css — v4 설정 */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.7 0.15 200);
  --color-surface: oklch(0.98 0 0);
  --font-heading: 'Pretendard', sans-serif;
  --radius-card: 0.75rem;
}

/* 다크 모드 */
@theme dark {
  --color-surface: oklch(0.12 0 0);
}

Tailwind CSS v4 자동 소스 감지와 빌드 성능

v4의 빌드 엔진은 Rust로 재작성되어 대형 프로젝트에서 최대 5배 빠른 빌드 속도를 달성한다. 기존 v3에서는 content 배열에 스캔 경로를 명시해야 했지만, v4는 Git 추적 파일을 자동으로 스캔해 사용된 클래스를 감지한다. 개발 서버 시작 시간도 크게 단축되어 수십 개의 패키지를 포함하는 모노레포에서 효과가 두드러진다. 동적으로 생성되는 클래스가 있다면 @source 디렉티브로 추가 스캔 경로를 명시할 수 있다.

Tailwind CSS v4 자동 업그레이드 도구 활용

Tailwind 팀이 제공하는 npx @tailwindcss/upgrade 도구로 대부분의 변경사항을 자동 적용할 수 있다. 설정 파일 변환, 임시 중단된 유틸리티 교체, 플러그인 마이그레이션 등을 자동 처리하며, 수동 검토가 필요한 항목을 별도로 안내한다. 대형 프로젝트에서도 기본 마이그레이션은 10분 내에 완료되는 것이 일반적이다. 마이그레이션 후에는 전체 페이지를 시각적으로 검토하여 디자인이 의도대로 유지되는지 확인해야 한다.

Tailwind CSS v4 주요 Breaking Changes 정리

v4에서 일부 유틸리티 클래스가 리네이밍되고, 그림자·투명도·색상 스케일이 재정의되었다. transform, filter, backdrop-filter는 이제 자동 적용되어 별도 클래스가 불필요하며, shadow 클래스의 기본값도 변경되었다. 임의 값 문법 일부가 변경되어 text-[14px] 같은 패턴은 유지되지만 일부 특수 문법은 조정이 필요하다. 완전히 동일한 디자인을 유지하려면 변경된 기본값을 @theme에서 v3 값으로 재선언하면 된다.

Tailwind CSS v4 @theme로 디자인 시스템 구축

@theme 블록에서 선언한 CSS 변수는 Tailwind 유틸리티와 직접 연결된다. --color-brand를 선언하면 text-brand, bg-brand, border-brand 유틸리티가 자동 생성된다. 기존에는 tailwind.config.js의 extend.colors에 추가하던 작업이 CSS 변수 선언만으로 처리된다. 이 접근 방식은 CSS 변수를 통해 런타임에서 테마를 동적으로 변경하는 것도 가능하게 한다.

Tailwind CSS v4 Vite 플러그인 네이티브 통합

v4에서는 PostCSS 플러그인 외에 Vite 전용 플러그인 @tailwindcss/vite가 제공된다. PostCSS 설정 파일 없이 vite.config.ts에 플러그인을 추가하는 것만으로 통합이 완료된다. HMR 성능도 향상되어 스타일 변경 시 브라우저 반영 속도가 빨라진다. Next.js 환경에서는 여전히 PostCSS 방식을 사용하며, Vite 기반 프레임워크(SvelteKit, Astro, Nuxt)에서 Vite 플러그인의 이점이 더 크다.