본문 바로가기
Q&A2026년 8월 24일1분 읽기

Tailwind v4로 올렸더니 tailwind.config.js의 커스텀 색상/폰트가 전부 안 먹습니다

t
tw_bomi
조회 627댓글 1

Tailwind CSS를 v3에서 v4로 업그레이드했는데, 빌드는 에러 없이 되는데 tailwind.config.js에 정의한 커스텀 컬러(brand, accent 등)랑 폰트가 유틸리티 클래스로 안 먹습니다. bg-brand 같은 걸 쓰면 그냥 무시돼요.

// tailwind.config.js
module.exports = {
  theme: { extend: { colors: { brand: '#1a73e8' } } }
}

기본 유틸리티(bg-blue-500 같은 거)는 멀쩡히 잘 나오는데 제가 정의한 커스텀만 안 나옵니다. 마이그레이션 문서를 봐도 뭐가 바뀐 건지 헷갈리네요. config 파일 위치나 이름은 그대로인데 왜 이것만 무시되는 걸까요?

tailwindcsstailwind-v4css프론트엔드
이전 글
SSE 스트리밍이 nginx 뒤에서는 실시간으로 안 오고 응답 끝날 때 한꺼번에 옵니다
다음 글
안녕하세요 개발자님

댓글 1

김김영삼2개월 전
v4에서 설정 철학이 통째로 바뀐 게 원인입니다. v3는 JS config(tailwind.config.js)가 중심이었는데, v4는 CSS-first로 가서 테마를 CSS 안에서 정의해요. 그래서 v4는 tailwind.config.js를 기본적으로 자동으로 읽지 않습니다. 기본 유틸은 v4 내장이라 나오고, 님이 JS config에 넣은 커스텀만 통째로 무시되는 이유가 그거예요.

v4 방식으로 옮기면 이렇게 됩니다. 엔트리 CSS에서 @import "tailwindcss"; 한 뒤, 테마를 @theme 블록으로 선언하세요.

@import "tailwindcss";

@theme {
--color-brand: #1a73e8;
}

이러면 bg-brand, text-brand 같은 유틸이 생성됩니다. 네이밍이 규칙이에요. 색은 --color-* , 폰트는 --font-* , 이런 네임스페이스로 넣으면 거기 맞는 유틸이 자동으로 만들어집니다. v3의 @tailwind base/components/utilities 세 줄 디렉티브도 이제 @import "tailwindcss" 한 줄로 대체됐고, PostCSS 플러그인도 @tailwindcss/postcss 로 바뀌었으니 postcss 설정도 같이 확인하세요.

기존 JS config를 당장 다 옮기기 부담되면 임시 다리는 있습니다. CSS에 @config "./tailwind.config.js"; 를 명시적으로 적어주면 v4가 그 파일을 읽어줍니다. 자동으로는 안 읽으니 이 한 줄이 있어야 해요. 다만 이건 과도기용이고, 결국 @theme 방식으로 옮기는 걸 권합니다.

손으로 다 고치기 싫으면 npx @tailwindcss/upgrade 돌려보세요. config를 CSS @theme 로 상당 부분 자동 변환해줍니다. 돌린 뒤 커스텀 색/폰트 잘 옮겨졌는지랑 postcss 설정만 눈으로 한 번 확인하면 됩니다.
Ctrl+Enter로 등록