[Next.js] vanilla-extract로 다크모드(dark mode) 구현하기 (feat.next-themes)

📖 들어가며

Next.js 14버전 app router 프로젝트의 styled-comoponents에서 vanilla-extarct로 마이그레이션을 진행함에 있어서 다크모드 기능도 같이 진행하게 되었습니다.

 

그리고 이번 다크모드를 적용하면서 next-themes를 활용해 봤는 데 사용 경험이 매우 좋았습니다.

 

또한, app router에서 vanilla-extract로 다크모드를 구현함에 있어서 참고자료가 많지 않다는 것을 깨달았기 때문에 글을 작성하려 합니다.

 

그럼 이제 Next.js app router에서 vanilla-extract + next-themes를 활용한 다크모드를 한번 구현해 봅시다.

🧐 next-themes 소개

https://github.com/pacocoursey/next-themes

GitHub - pacocoursey/next-themes: Perfect Next.js dark mode in 2 lines of code. Support System preference and any other theme wi

먼저 간단하게 next-themes가 무엇인지 소개하겠습니다.

 

next-theme는 제목에서 유추할 수 있듯이 Next.js 환경에서 테마를 쉽게 설정할 수 있도록 도와줍니다.

 

또한, localStorage를 활용해서 테마를 사용합니다.

 

해당 Github에서 next-themes 장점을 발췌해 보자면 아래와 같습니다.

• ✅ 단 두 줄의 코드로 완벽한 다크 모드
• ✅ prefers-color-scheme를 통한 시스템 테마 기반 설정
• ✅ color-scheme를 사용한 테마 브라우저 UI
• ✅ Next.js 13 지원 appDir
• ✅ 로드 시 플래시 없음(SSR 및 SSG 모두)
• ✅ 탭과 창에서 테마 동기화
• ✅ 테마 변경 시 깜박임 비활성화
• ✅ 페이지를 특정 테마로 강제 적용
• ✅ 클래스 또는 데이터 속성 선택기
• ✅ useTheme Hook

제가 크게 매력을 느낀 부분에는 강조를 했습니다.

 

실제로 next-themes를 사용하기 이전에는 Context API와 커스텀 훅을 생성해서 사용하는 방식으로 진행했었습니다.

 

이러한 방식을 사용하다가 next-themes를 사용해 본 결과로 next.js에서 다크모드의 깜빡임 현상을 해결하기 위해서 DOM 렌더링 이전에 script의 dangerouslySetInnerHTML를 활용해서 방지하는 방법의 해결하는 방안을 많이 볼 수 있습니다.

 

하지만 next-themes를 사용하면서 이러한 추가적인 코드가 필요하지 않았기 때문에 사용하지 않을 이유가 없다고 느꼈습니다.

 

그럼 이제 설치부터 해주고 시작합시다!

$ npm install next-themes
# or
$ yarn add next-themes

✔️ 라이트 모드 및 다크 모드 theme 생성

적용하기에 앞서 라이트 모드와 다크 모드에 맞는 색상을 정의해야 합니다.

 

vanilla-extract에서는 createThemeContract와 createTheme을 활용해서 각각 정의할 수 있습니다.

// globalThemes.css.ts

import {
  globalStyle,
  createThemeContract,
  createGlobalTheme,
  createTheme,
} from '@vanilla-extract/css';

export const global = createGlobalTheme(':root', {
  fontFamily: {
    notoSansKR: `var(--font-noto-sans-kr)`,
  },
  fontSize: {
    xLarge: '48px',
    large: '36px',
    medium: '28px',
    regular: '18px',
    small: '16px',
    micro: '14px',
  },
  fontWeight: {
    normal: '400',
    medium: '500',
    large: '700',
  },
  ...
  color: {
   ...
  },
});

const themeColor = createThemeContract({
  color: {
    mainBackground: null,
    contentBackground: null,
    mainFontColor: null,
    borderColor: null,
    gradient: null,
  },
});

export const lightTheme = createTheme(themeColor, {
  color: {
    mainBackground: '#f7f9fa',
    contentBackground: '#ffffff',
    mainBackground: '0 0% 100%',
    contentBackground: '0 0% 100%',
    mainFontColor: '#2c2c2c',
    borderColor: '#cbc9f9',
    gradient: 'linear-gradient(#39598A, #79D7ED)',
  },
});

export const darkTheme = createTheme(themeColor, {
  color: {
    mainBackground: '#1d1d1d',
    contentBackground: '#2c2c2c',
    mainBackground: '222.2 84% 4.9%',
    contentBackground: '222.2 84% 8.9%',
    mainFontColor: '#ffffff',
    borderColor: '#b1b1b3',
    gradient: 'linear-gradient(#091236, #1E215D)',
  },
});

export const vars = { ...global, themeColor };

...

globalStyle('body', {
  fontSize: global.fontSize.small,
  backgroundColor: `hsl(${vars.themeColor.color.mainBackground})`,
  userSelect: 'none',
  transition: 'all 0.25s linear',
});

 

위 코드를 설명하겠습니다.

 

먼저, 테마 간에 변경되지 않는 모든 테마 변수를 포함하는 global theme을 만들었습니다.

 

createThemeContract를 통해서 모드 간에 어떠한 속성들이 사용될 것인지 '틀'을 잡아주었습니다.

const themeColor = createThemeContract({
  color: {
    mainBackground: null,
    contentBackground: null,
    mainFontColor: null,
    borderColor: null,
    gradient: null,
  },
});

createThemeContract의 value들에게 값을 넣지 않은 이유는 속성에 맞는 값들을 재사용해야 하기 때문입니다.

 

즉, createThemeContract는 css를 생성하지 않습니다. 정적 타이핑을 위한 contract를 생성합니다.

 

또한, 라이트 모드와 다크 모드의 테마는 동시에 불러올 상황이 없기 각각 불러올 수 있어서 코드 스플리팅 이점도 볼 수 있습니다.

 

이후 createTheme을 활용해서 첫 번째 인자로 위에서 정의한 themColor를 넣고 두 번째 인자를 객체에 theme contract에 맞게 값을 지정할 수 있습니다.

export const lightTheme = createTheme(themeColor, {
  color: {
    mainBackground: '#f7f9fa',
    contentBackground: '#ffffff',
    mainBackground: '0 0% 100%',
    contentBackground: '0 0% 100%',
    mainFontColor: '#2c2c2c',
    borderColor: '#cbc9f9',
    gradient: 'linear-gradient(#39598A, #79D7ED)',
  },
});

export const darkTheme = createTheme(themeColor, {
  color: {
    mainBackground: '#1d1d1d',
    contentBackground: '#2c2c2c',
    mainBackground: '222.2 84% 4.9%',
    contentBackground: '222.2 84% 8.9%',
    mainFontColor: '#ffffff',
    borderColor: '#b1b1b3',
    gradient: 'linear-gradient(#091236, #1E215D)',
  },
});

 

그다음, 글로벌 스타일과 theme contract인 themeColor를 하나의 객체로 사용될 수 있도록 export 합니다.

export const vars = { ...global, themeColor };

 

꼭 body에 대해서 themeColor에 대한 속성을 지정해 주세요.
default로 설정된 body의 theme 색상이 있어야 하는 것 같습니다.
지정하지 않으면 next-themes에 의해서 다크모드 설정 시 브라우저 기본 색상(white)으로 잠시 보였다가 적용이 되는 현상(깜빡이는 현상)을 겪었습니다.

 

globalStyle('body', {
  ...
  backgroundColor: `hsl(${vars.themeColor.color.mainBackground})`,
  ...
});

 

theme 정의에 대한 부분은 이제 끝났습니다!

✔️ next-themes의 ThemeProvider 정의

next-themse를 적용하기 위해서는 next-themse가 제공하는 ThemeProvider를 생성 후 사용할 수 있습니다.

// context/ThemeProvider.tsx
'use client';

import { darkTheme, lightTheme } from 'src/styles/globalTheme.css';
import { ThemeProvider } from 'next-themes';

const Provider = ({ children }: { children: React.ReactNode }) => {
  return (
    <ThemeProvider
      attribute="class"
      defaultTheme="system"
      value={{
        light: lightTheme,
        dark: darkTheme,
      }}
    >
      {children}
    </ThemeProvider>
  );
};

export default Provider;

ThemeProvider는 내부적으로 ContextAPI를 사용하고 있기 때문에 해당 컴포넌트는 클라이언트 컴포넌트가 되어야 합니다.

 

즉, 'use client'를 명시해 줍니다.

여기서 많은 분들이 의문을 가지고 저 또한 의문을 가진 부분이 있었습니다.

ThemeProvider는 클라이언트 컴포넌트인데, 이걸로 감싸게 되면 결국 자식들은 모두 클라이언트 컴포넌트가 되는 것이 
아닌가? 에 대한 의문이었습니다.

하지만 클라이언트 컴포넌트의 props로 서버 컴포넌트로 전달하는 경우에는 그렇지 않습니다.

아래 공식문서의 해당 섹션을 참고해 주세요

 

https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#interleaving-server-and-client-components

Rendering: Composition Patterns | Next.js

 

다시 본론으로 돌아가겠습니다.

 

vanilla-extract는 각 테마에 대한 className을 제공하므로 attribute를 'class'로 설정합니다.

 

이후 defaultTheme으로 기본으로 설정할 theme 모드를 설정할 수 있습니다.

 

value를 통해 우리가 정의했던 라이트 모드와 다크 모드 theme을 불러와서 값에 넣어줍니다.

 <ThemeProvider
      attribute="class"
      defaultTheme="system"
      value={{
        light: lightTheme,
        dark: darkTheme,
      }}
    >

만약 시스템에 정의된 컬러를 사용하고 싶지 않다면 아래 코드처럼 사용할 수 있습니다.

enableSystem의 기본값은 true입니다.

 <ThemeProvider
      attribute="class"
      enableSystem={false}
      value={{
        light: lightTheme,
        dark: darkTheme,
      }}
    >

✔️ next-themes의 ThemeProvider 사용

// layout.tsx
...
import 'src/styles/reset.css';
import 'src/styles/globalTheme.css';
...
import ThemeProvider from 'src/context/ThemeProvider';
import DarkModeBtn from './_components/Buttons/DarkModeBtn';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko" suppressHydrationWarning>
      <body className={`${notoSansKr.className}`}>
        <ThemeProvider>
          <GoogleAnalytics />
          <div className={style.container}>
            <DarkModeBtn />
            {children}
            <Footer />
          </div>
        </ThemeProvider>
      </body>
      <KakaoScript />
    </html>
  );
}

이전에 정의한 ThemeProvider를 body 아래에 감싸줍니다.

 

body 위에 감싸버리면 아래 에러를 맞이할 수 있으니 주의하세요.

Hydration failed because the initial UI does not match what was rendered on the server.

https://react.dev/errors/418?invariant=418

Minified React error #418 – React

그리고 html 속성으로 suppressHydrationWarning을 추가합니다.

 <html lang="ko" suppressHydrationWarning>

서버 컴포넌트 사용 시 서버와 클라이언트에서 렌더링 한 컨텐츠가 다를 경우 경고가 발생합니다.

https://react.dev/reference/react-dom/components/common#common-props

즉, 서버는 라이트 모드인지 다크 모드인지 내가 설정한 테마에 대해서 알 수 없습니다.

 

지금 같은 경우에는 테마를 설정하는 데에 있어서 피할 수 없기 때문에 적절한 사용입니다.

 

suppressHydrationWarning를 사용함으로써 경고를 막을 수 있습니다.

✔️ useTheme 및 다크모드 버튼 적용

// DarkModBtn.tsx
'use client';

import SunnyIcon from 'public/images/sunny.svg';
import MoonIcon from 'public/images/moon.svg';
import * as style from './darkModeBtn.css';
import { assignInlineVars } from '@vanilla-extract/dynamic';
import { useTheme } from 'next-themes';
import { useEffect, useState } from 'react';

const DarkModeBtn = () => {
  const [mounted, setMounted] = useState(false);
  const { resolvedTheme, setTheme } = useTheme();

  useEffect(() => setMounted(true), []);

  if (!mounted) return <div className={style.container} />;

  return (
    <div className={style.container}>
      <button
        className={style.button}
        onClick={() => setTheme(resolvedTheme === 'light' ? 'dark' : 'light')}
        aria-label="DarkModeBtn"
      >
        <SunnyIcon
          className={style.svg}
          style={assignInlineVars({
            [style.lightMode]: resolvedTheme === 'light' ? '0' : '100px',
          })}
        />
        <MoonIcon
          className={style.svg}
          style={assignInlineVars({
            [style.darkMode]: resolvedTheme === 'light' ? '-100px' : '0',
          })}
        />
      </button>
    </div>
  );
};

export default DarkModeBtn;

코드에서 mounted가 true면 버튼을 정상적으로 렌더링 하는 코드를 볼 수 있습니다.

 

이 부분 또한 useTheme은 localStorage를 통해 현재 테마를 가져오기 때문에  Hydration Missmatch를 피하기 위해 클라이언트에 마운트 되었을 때 useTheme으로 현재 theme을 정상적으로 가져올 수 있도록 합니다.

 

그래서 마운트가 되지 않았을 때는 같은 크기인 빈 div를 보일 수 있도록 했습니다.

if (!mounted) return <div className={style.container} />;

같은 크기의 빈 div를 넣은 이유는 Layout Shift 현상을 피하기 위해서입니다.
Layout Shift는 reflow가 발생하고 주변 콘텐츠가 밀리는 현상이 발생하기 때문에 UX(사용자 경험) 측면에서 좋지 않습니다.

이후 실질적인 button에 대해서 useTheme 훅의 resovedTheme과 setTheme을 이용해서 테마를 전환할 수 있도록 할 수 있습니다.

...
import { useTheme } from 'next-themes';
...
const { resolvedTheme, setTheme } = useTheme();
...
<div className={style.container}>
      <button
        className={style.button}
        onClick={() => setTheme(resolvedTheme === 'light' ? 'dark' : 'light')}
        aria-label="DarkModeBtn"
      >
        <SunnyIcon
          className={style.svg}
          style={assignInlineVars({
            [style.lightMode]: resolvedTheme === 'light' ? '0' : '100px',
          })}
        />
        <MoonIcon
          className={style.svg}
          style={assignInlineVars({
            [style.darkMode]: resolvedTheme === 'light' ? '-100px' : '0',
          })}
        />
      </button>
</div>

 

reslovedTheme은 enableSystem이 true이고 활성 테마가 "system"인 경우 시스템 기본 설정이 "dark" 또는 "light"로 확인되었는지 여부를 반환합니다. 그렇지 않으면 그냥 현재 테마 상태를 반환합니다.

 

setTheme은 이름 그대로 theme 상태를 업데이트하는 역할입니다.

 

매우 직관적이지 않나요?

 

그럼 이 버튼을 가지고 이제 라이트 모드와 다크 모드를 전환할 수 있습니다!

✔️ body 외에 다른 컴포넌트에 theme 모드에 따른 색상 적용

이전에 body는 globalStyle로 적용했습니다.

추가적으로 다른 컴포넌트에서 theme에 따른 색상을 보여주기 위해서는 아래와 같이 사용할 수 있습니다.

import { style } from '@vanilla-extract/css';
import { vars } from 'src/styles/globalTheme.css';

export const container = style({
  ...
  color: vars.themeColor.color.mainFontColor,
  ...
});

이전에 export 한 vars에서 theme contract를 통해서 theme을 정의한 css 변수를 가져와 적용합니다.

✅ 결과

그럼 브라우저에서 어떻게 적용되는지 확인해 볼까요?

결과 화면

우리가 정의한 ThemeProvider에 attribute를 'class'로 사용했기 때문에 class에 따른 className이 각 테마의 상태에 맞게 변경되고 있습니다.

 

또한, 우측에 라이트 모드와 다크 모드에 따른 CSS가 각각 사용되는 것을 볼 수 있습니다.

이건 우리가 ThemeProvider에서 value로 lightTheme과 darkTheme을 넣어줬기 때문에 그것을 가지고 보여주게 되는 것입니다.

개발 모드에서는 다크모드 설정 후 새로 고침 시 잠시 깜빡이는 현상이 보일 수 있습니다.
build 후 production 환경에서 확인하면 깜빡이는 현상이 없는 것을 확인할 수 있습니다.

🧐 부록: next-themse 코드 들여다보기

localStorage를 통해서 테마를 보여주는데 새로고침 시 깜빡임도 없고, 시스템 테마를 확인해서 보여주고 등등..

이런 것들이 어떻게 구현되어 있길래 가능한 건지 궁금한 마음에 코드를 찾아봤습니다 😂

 

https://github.com/pacocoursey/next-themes/blob/main/packages/next-themes/src/index.tsx

 

핵심적인 부분으로 생각하는 몇 군데 해석해보려 합니다.

 

scriptSrc 함수를 통해 어떻게 깜빡임 없이 초기 상태를 보여주도록 하고 있는지 유추할 수 있었습니다.

 

간단하게 코드를 해석해 보자면, 로컬스토리지에 저장된 theme이 있으면 해당 theme을, 없으면 prefers-color-scheme을 통해 theme을 updateDoM을 통하는 함수로, script의 dangerousySetInnerHTML을 통해서 주입하고 있었습니다.

 

그리고 위 코드는 테마를 적용하는 함수인 것 같습니다.

document.documentElement 즉 html에 클래스를 추가하고 있네요.

 

아래 사진을 보시면 document.documentElement은 html입니다.

 

이전에 위 결과 화면에서 html에서 변경이 되는 것을 확인할 수 있었습니다.

📕 마무리

Next.js app router에서 vanilla-extract와 next-themes를 통한 다크모드를 적용할 수 있었습니다.

 

vanilla-extract의 강력한 theme 지원과 next-themese로 인한 아주 짧은 코드로 성공적으로 적용할 수 있었네요.

 

매우 좋은 경험이었습니다 :)

 

구현 시 참고했던 포스트들:

https://www.youtube.com/watch?v=7zqI4qMDdg8

https://www.youtube.com/watch?v=RTAJ-enfums

https://www.joo-dev.com/post/detail/NEXTJS-Vanilla-Extract-%EB%8F%84%EC%9E%85%ED%95%98%EA%B8%B0--Dark-mode-%EA%B5%AC%ED%98%84-NextJS-%EB%B8%94%EB%A1%9C%EA%B7%B8

https://samuelkraft.com/blog/vanilla-extract-with-next-themes