테일윈드 v4, Next.js, CSS 변수, 플러그인 | 기존 프로젝트를 v4로 올릴 때 어디서 막히나?
Tailwind CSS v4의 핵심 변화인 tailwind.config.js 삭제·@theme 블록·CSS 변수 기반 테마 정의를 Next.js 프로젝트 기준으로 정리한다. 업그레이드 도구 실행 순서, 플러그인 호환 문제, 임의 값 문법 변화, v4 전환 여부 판단 기준까지 포함.
Tailwind CSS v4가 2025년 초에 정식 릴리스됐습니다. v3와 설정 방식이 많이 달라서 기존 프로젝트를 그냥 버전만 올리면 빌드가 깨집니다. 설정 파일이 tailwind.config.js에서 CSS 변수 기반으로 바뀌었고, @tailwind 지시어도 사라졌습니다. 제가 Next.js 프로젝트 세 개를 v4로 올리면서 막힌 자리를 정리합니다.
Tailwind v4의 빌드 속도가 v3보다 10배 빠르다는 얘기는 공식 문서에서 말하는 수치입니다. 실제로 개발 서버 HMR 속도가 올라가는 건 체감됩니다. 단, 마이그레이션 비용이 있습니다. 새로 시작하는 프로젝트라면 v4부터 시작하는 게 낫고, 기존 프로젝트는 마이그레이션 공식 도구를 먼저 돌려보는 게 순서입니다.
v3에서 v4로 바뀐 것들
바뀐 것 중 개발자가 직접 손대야 하는 부분만 추립니다.
항목
v3
v4
설정 파일
tailwind.config.js
CSS 파일 안의 @theme 블록
진입점 지시어
@tailwind base; utilities; components;
@import "tailwindcss";
커스텀 색상
config의 theme.extend.colors
CSS 변수 --color-brand: … in @theme
플러그인
config에 plugins: [require(…)]
@plugin "…" 지시어
PostCSS 설정
postcss.config.js에 tailwindcss 추가
자동 감지 (수동 설정 불필요)
content 경로
config의 content: ["./pages/**/*"]
자동 감지 (명시 필요 없음, 일부 예외)
가장 큰 변화는 JavaScript 설정 파일이 CSS 파일로 통합됐다는 것입니다. tailwind.config.js를 완전히 삭제하고 CSS 파일 안에서 테마를 정의합니다. 기존 v3 프로젝트에는 이게 가장 큰 작업입니다.
Next.js 프로젝트에 Tailwind v4 설치하는 순서
신규 프로젝트는 Next.js 15 이상에서 create-next-app이 Tailwind v4 옵션을 제공합니다. 기존 프로젝트는 아래 순서로 진행합니다.
기존 v3 프로젝트를 v4로 올리는 명령
# 1. 공식 업그레이드 도구 실행 (파일 자동 수정)
npx @tailwindcss/upgrade
# 2. 도구가 안 되면 수동 설치
npm install tailwindcss@next @tailwindcss/postcss@next
# 또는 pnpm
pnpm add tailwindcss@next @tailwindcss/postcss@next
# 3. PostCSS 플러그인 교체
# postcss.config.js 또는 postcss.config.mjs 확인
# 'tailwindcss' → '@tailwindcss/postcss' 로 교체
@tailwindcss/upgrade를 먼저 실행하면 대부분의 설정을 자동으로 옮겨줍니다. 하지만 커스텀 플러그인, 사용자 정의 클래스가 많을수록 수동으로 손봐야 할 부분이 늘어납니다.
업그레이드 도구를 돌리고 나서도 빌드가 깨지는 경우가 있습니다. 제가 직접 만난 것들입니다.
⚠️ v3 플러그인 호환성 | @tailwindcss/forms, @tailwindcss/typography, @tailwindcss/aspect-ratio는 v4용 버전을 따로 설치해야 합니다. 기존 npm 패키지를 그대로 두면 충돌이 납니다. @plugin "@tailwindcss/typography" 지시어로 CSS에서 부릅니다.
⚠️ 임의 값(arbitrary value) 문법 일부 변경 | v3의 text-[#333]는 그대로지만, bg-[url('/img.png')]처럼 CSS 함수가 포함된 임의 값은 이스케이프 방식이 바뀌었습니다. 빌드 후 화면을 직접 확인해야 합니다.
⚠️ content 경로 자동 감지 예외 | 기본 감지는 .js, .ts, .jsx, .tsx, .html을 읽습니다. .mdx, .vue, 커스텀 확장자를 쓰면 @source 지시어로 직접 지정해야 합니다.
