AI 풀스택 연구소 AI 코딩 도구와 풀스택 개발 실무를 정리하는 정보 사이트

프론트엔드·풀스택 개발

Tailwind CSS v4 마이그레이션: 업그레이드 도구와 바뀐 설정·유틸리티 정리

@import 방식, CSS 기반 @theme 설정, 이름이 바뀐 유틸리티와 기본값 변화 점검

Huni

핵심 요약

  1. v4는 Safari 16.4+, Chrome 111+, Firefox 128+을 대상으로 하므로 구형 브라우저가 필요하면 v3.4에 머문다.
  2. 새 브랜치에서 npx @tailwindcss/upgrade를 실행하고 diff를 파일 유형별로 검토한다.
  3. @tailwind 지시어는 @import "tailwindcss"로, 테마는 CSS의 @theme으로 옮긴다.
  4. 테두리 기본색과 ring 두께처럼 클래스 이름은 같지만 결과가 바뀐 기본값을 별도로 점검한다.

Tailwind CSS v4는 설정 방식부터 바뀌었다. JavaScript 설정 파일 대신 CSS 안에서 테마를 정의하고, @tailwind 지시어 세 줄이 @import 한 줄로 바뀌었으며, 일부 유틸리티는 이름과 기본값이 달라졌다. 업그레이드 도구가 대부분을 자동으로 바꿔 주지만, 화면이 미묘하게 달라지는 부분은 사람이 확인해야 한다. 이 글은 공식 업그레이드 가이드를 바탕으로 순서와 점검 항목을 정리한다. AI 도구로 만든 보일러플레이트를 정리할 때의 원칙은 보일러플레이트 자동화 글에서 다뤘다.

업그레이드 전에 확인할 조건

항목v4 요구 사항맞지 않으면
Node.js업그레이드 도구 실행에 Node.js 20 이상Node 버전부터 올림
브라우저Safari 16.4+, Chrome 111+, Firefox 128+구형 브라우저 지원이 필요하면 v3.4 유지
전처리기Sass, Less, Stylus와 함께 쓰는 구성 미지원전처리기 의존 부분을 먼저 정리
설정 APIcorePlugins 옵션, resolveConfig() 미지원CSS 변수 기반으로 대체

사내 시스템처럼 구형 브라우저를 지원해야 한다면 무리해서 올리지 않는다. 가이드도 오래된 브라우저 지원이 필요하면 v3.4에 머물라고 안내한다.

1단계: 새 브랜치에서 업그레이드 도구 실행

git switch -c chore/tailwind-v4
npx @tailwindcss/upgrade
git diff --stat

가이드는 도구를 새 브랜치에서 실행하고 변경 사항을 검토한 뒤 병합하라고 권한다. 도구는 의존성, 설정, 템플릿 파일의 클래스 이름을 함께 바꾸므로 diff가 크다. 파일 유형별로 나눠 검토한다.

2단계: CSS 진입점과 패키지 확인

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";
빌드 환경v4 패키지
PostCSS@tailwindcss/postcss
Vite@tailwindcss/vite
CLI@tailwindcss/cli

v4는 import 처리와 벤더 접두사를 자체적으로 다루므로 postcss-import와 autoprefixer는 제거할 수 있다.

3단계: 테마 설정을 CSS로 옮기기

@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.62 0.19 255);
  --breakpoint-3xl: 120rem;
}

@theme에 정의한 변수는 유틸리티 클래스(bg-brand-500, 3xl:)로 쓸 수 있다. 기존 JavaScript 설정을 당장 옮기기 어렵다면 @config "../../tailwind.config.js";로 불러와 단계적으로 이전할 수 있다. 사용자 정의 유틸리티는 @layer utilities 대신 @utility 문법으로 바뀌었다.

4단계: 이름과 기본값이 바뀐 유틸리티 점검

v3v4비고
shadow-sm / shadowshadow-xs / shadow-sm크기 이름이 한 단계씩 이동
rounded-sm / roundedrounded-xs / rounded-sm같은 방식으로 이동
blur-sm / blurblur-xs / blur-smdrop-shadow, backdrop-blur도 동일
outline-noneoutline-hidden접근성 포커스 표시 확인
ring(3px, 파랑)ring(1px, currentColor)v3 모양은 ring-3 ring-blue-500
테두리 기본색 gray-200테두리 기본색 currentColorborder만 쓴 곳에 색 지정
!flexflex!important 표시가 뒤로 이동
bg-[--brand]bg-(--brand)CSS 변수 임의값 문법 변경
first:*:pt-0*:first:pt-0변형 적용 순서가 왼쪽→오른쪽으로

자동 변환이 가장 놓치기 쉬운 부분은 기본값 변화다. 클래스 이름은 그대로인데 결과가 달라지기 때문이다. border만 쓰고 색을 지정하지 않은 요소는 글자색과 같은 진한 테두리가 되고, ring만 쓴 포커스 표시는 가늘어진다.

5단계: 화면 회귀 확인

  1. 프로젝트에서 색 없이 border, ring만 쓴 위치를 검색해 의도한 색을 명시한다.
  2. 버튼·입력창의 포커스 표시를 키보드로 이동하며 확인한다(outline-hidden, ring 두께 변화).
  3. 그림자·모서리 둥글기가 한 단계씩 바뀌었는지 주요 화면 스크린숏을 v3 브랜치와 비교한다.
  4. space-x, divide 유틸리티를 쓴 목록의 간격을 확인한다. 가이드는 선택자 변경으로 대형 페이지 성능을 개선했으며 flex·grid의 gap 사용을 권한다.
  5. 빌드 결과 CSS 크기와 빌드 시간을 기록해 둔다.

AI 도구가 v3 문법으로 새 코드를 계속 만들어 내지 않도록, 규칙 파일에 "Tailwind v4 문법 사용, important는 접미사, 그림자 이름은 v4 기준"을 적어 둔다. 규칙 파일 작성은 Cursor Rules 작성법 글을 참고한다.

초보자가 자주 실수하는 포인트

  • 기본 브랜치에서 바로 업그레이드 도구를 실행하는 경우
  • border만 쓴 요소의 색 변화를 확인하지 않는 경우
  • outline-none 변환 후 키보드 포커스 표시를 점검하지 않는 경우
  • AI 도구가 계속 v3 문법을 생성하도록 규칙을 갱신하지 않는 경우

체크리스트

  • 대상 브라우저가 v4 지원 범위에 들어가는가
  • CSS 진입점이 @import "tailwindcss"로 바뀌었는가
  • 빌드 플러그인 패키지가 v4용으로 교체됐는가
  • 색 없는 border·ring 사용처를 점검했는가
  • 주요 화면 스크린숏 비교를 마쳤는가

자주 묻는 질문

tailwind.config.js를 바로 지워야 하나요?

필수는 아니다. @config 지시어로 기존 JS 설정을 불러와 쓰면서 @theme으로 단계적으로 옮길 수 있다.

Sass를 쓰는 프로젝트도 올릴 수 있나요?

가이드는 v4가 Sass, Less, Stylus 같은 전처리기와 함께 쓰는 구성을 지원하지 않는다고 밝힌다. 전처리기 의존 부분을 먼저 정리한다.

업그레이드 도구가 모든 파일을 바꿔 주나요?

대부분의 의존성·설정·클래스 이름을 바꾸지만, 기본값 변화로 인한 시각적 차이는 사람이 확인해야 한다.

참고 자료 · 검증 기준

위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.

이 글은 위 참고 자료를 바탕으로 정리했으며, 내용은 운영 과정에서 순차적으로 보완될 수 있습니다.

관련 글