Tailwind v3 → v4 마이그레이션 진행 중인데 미친 듯이 헤매고 있습니다.
환경: Tailwind CSS 4.2.2, Next.js 16.2, PostCSS 8.5, @tailwindcss/postcss
증상:
next dev에서: 다크모드 토글 → 색 정상 적용 ✅next build && next start에서: 다크모드 토글해도 색 안 바뀜 ❌- 라이트모드는 production에서도 정상
- build 출력에 에러 없음, lint 통과
설정:
/* app/globals.css */
@import "tailwindcss";
@theme {
--color-bg: oklch(98% 0 0);
--color-fg: oklch(15% 0 0);
--color-primary: oklch(70% 0.15 220);
}
.dark {
--color-bg: oklch(15% 0 0);
--color-fg: oklch(95% 0 0);
}
tailwind.config.js는 v4부터 안 쓴다 해서 안 만들었습니다. html.dark로 토글하는 로직은 모드 토글 라이브러리(next-themes)가 처리하고, dev에선 잘 됩니다.
production 빌드 결과의 CSS를 보면 .dark { ... } 블록이 통째로 사라져 있더라고요. PostCSS purge가 잘못 처리하는 건가요?
댓글 3
v4의 가장 흔한 함정입니다. 정답부터: 다크모드 변수는 @theme 안에 직접 변형 정의로 넣어야 하고,
.dark { --color-bg: ... }형태는 v4 PostCSS 플러그인의 purge에 의해 제거됩니다.이유는 v4가 "tailwind가 직접 알지 못하는 셀렉터"의 변수 정의를 자동으로 안 가져가기 때문입니다. v3 JIT처럼 동작하지만 더 엄격해졌어요.
해결 — @custom-variant + @theme
핵심은 마지막 줄
@source inline("dark"). PostCSS 플러그인에게 "이 셀렉터는 코드에 안 보여도 항상 포함시켜라"고 알려주는 v4 신규 디렉티브입니다.또 다른 방법 — prefers-color-scheme 활용
시스템 다크모드를 그대로 따라가도 되면 더 간단합니다.
왜 dev에서는 됐나
v4 PostCSS의 Lightning CSS 통합이 dev mode에서는 purge를 안 합니다(빠른 HMR을 위해). production build에서만 purge가 활성화되어 거기서 처음 깨지는 거죠. dev에서 멀쩡한 게 함정입니다. v4 마이그레이션은 항상 production build로 검증해야 해요.
저도 v4 옮길 때 같은 곳에서 막혔는데 추가로 만난 함정 공유드리면:
1) Lightning CSS의 oklch 호환성
Lightning CSS가 oklch를 그대로 두는 게 아니라 RGB로 컴파일하는 경우가 있어요. Safari 16 미만이나 일부 구형 환경에선 호환 처리가 필요하고, 이 과정에서 다크 변수가 옅게 깎이는 케이스가 있었습니다.
2) next-themes의 hydration mismatch
v4와는 무관하지만 자주 겹쳐 발생합니다.
<html className="">와<html className="dark">의 차이로 hydration 에러가 나면 React 19.2 + Next 16에선 더 엄격해서 콘솔에 빨간 줄이 잡혀요.<ThemeProvider attribute="class" enableSystem disableTransitionOnChange>로 부드럽게 해결됩니다.3) build cache
이상하게 동작할 때
rm -rf .next node_modules/.cache한 번 해보시는 거 추천해요. Lightning CSS 캐시가 끈질겨서 변경 안 반영되는 경우가 있습니다.v4 문서를 다시 보니 이 디렉티브가 있긴 한데, 다크모드 섹션이 아니라 "Source detection" 섹션에 묻혀있어서 못 찾았네요. 마이그레이션 가이드에 다크모드 케이스로 명시해두면 좋겠어요.
두 분 답변 모두 정말 감사합니다. Lightning CSS targets 설정도 같이 적용했고 cache 정리 후 production 빌드 한 번 더 돌렸더니 깔끔합니다.