TailwindCSS V4에서 다크 모드가 적용되지 않는 이슈

들어가며

TailwindCSS V4에서 dark 클래스가 적용되지 않는 이슈

최근 TailwindCSS V4로 업데이트한 뒤에, 기존에 잘 작동하던 다크모드 클래스 (dark:)가 적용되지 않는 이슈가 발생했습니다. 찾아보니, V4로 업데이트되면서 다크 모드를 설정하는 방식에 중요한 변경이 있었습니다. V4에서는 tailwind.config.ts파일이 더이상 사용되지 않습니다.

왜 TailwindCSS v4에서 다크모드 클래스가 적용되지 않을까

이전 버전의 TailwindCSS에서는 tailwind.config.ts 파일에 다음과 같이 darkMode 옵션을 설정하여 클래스 기반의 다크 모드를 활성화했습니다.

V3 이하 버전 설정 (tailwind.config.ts)

1/** @type {import('tailwindcss').Config} */
2module.exports = {
3  // ...다른 설정들
4  darkMode: "class", // 'class' 전략으로 다크 모드 활성화
5}
View Code

하지만 TailwindCSS V4부터는 이 darkMode 설정이 제거되었습니다. 대신, globals.css 파일을 직접 수정하여 다크 모드 동작을 정의하는 방식으로 변경되었습니다.

✅ 해결책: @custom-variant로 다크 모드 활성화 하기

이벤트 핸들러로 다크 모드 상태를 직접 토글하는 경우, 이제부터는 글로벌 CSS 파일에 variant를 직접 추가해주어야 합니다.

1. globals.css 파일에 variants 추가

프로젝트의 globals.css파일에 다음과 같은 코드를 추가합니다.

1@import "tailwindcss";
2@custom-variant dark (&:where(.dark, .dark *));
View Code

💡 .dark 클래스가 적용된 모든 하위 요소에 dark: 스타일을 적용합니다.

2. 동작 방식

• @custom-variant: TailwindCSS V4에 새로 도입된 기능으로, 사용자 정의 변형(예: dark:, hover:)을 만들 수 있습니다.
• dark: 이 코드를 통해 dark: 접두사를 사용할 수 있게 됩니다.
• (&:where(.dark, .dark *))

• `.dark` : dark 클래스가 적용된 요소 자체를 선택합니다.
  

• `.dark *` : dark 클래스가 적용된 요소의 모든 자식 요소를 선택합니다.
  

• :where() : CSS 가상 클래스로, 괄호 안의 선택자들의 명시도(specificity)를 0으로 만듭니다. 이를 통해 다른 스타일에 예기치 않은 영향을 주는 것을 방지할 수 있습니다.

결과적으로, 이나 태그에 .dark 클래스를 추가하면, 그 하위의 모든 요소에서 dark: 변형 클래스가 올바르게 동작하게 됩니다.

결론

오랜 삽질의 허무한(?) 마무리

TailwindCSS V4 업데이트로 다크 모드에 대한 이전 설정이 deprecated 되었지만 @custom-variant 를 사용하는 새로운 방법은 더욱 간단하게 다크 모드를 적용할 수 있도록 지원합니다. 메이저 버전이 업데이트된 만큼 공식 문서를 좀 더 꼼꼼히 살펴야 한다는 교훈을 얻은 삽질(?)이었던 것 같습니다.