Next.js 프로젝트에 next-themes를 활용하여 라이트/다크 모드 테마 전환 기능을 구현하는 과정을 설명합니다.

Context

기존 웹 애플리케이션은 테마 전환 시 페이지 새로고침이나 복잡한 CSS 클래스 변경이 필요했다. 이로 인해 사용자 경험이 단절되고 개발자가 개별 컴포넌트마다 테마 로직을 직접 구현해야 했다.

Technical Solution

• Next.js 프로젝트 생성 시 pnpm create next-app 명령어로 스캐폴딩
• Tailwind CSS v4의 @theme 지시어를 활용하여 라이트/다크 모드 CSS 변수 정의
• next-themes 라이브러리의 ThemeProvider로 클라이언트-서버 간 하이드레이션 불일치 해결
• page.tsx에 mounted 상태 관리로 SSR 환경에서의 렌더링 이슈 방지
• 버튼 클릭 시 setTheme 함수 호출로 라이트/다크 모드 동적 전환

Impact

사용자가 테마를 전환해도 페이지 새로고침 없이 즉시 다크/라이트 모드로 변경됨

Key Takeaway

하이드레이션 에러를 방지하려면 mounted 상태를 활용하여 클라이언트 마운트 완료 후에만 테마 관련 UI를 렌더링해야 한다.