테마 유지와 화면 번쩍임 방지

페이지가 로드될 때 React는 localStorage를 읽고 올바른 테마를 적용하기 전에 JavaScript를 다운로드하고 파싱하고 실행해야 합니다. 이 공백 동안 브라우저는 기본 스타일로 렌더링합니다. 사용자가 어두운 모드를 선호하지만 기본값이 밝은 테마라면, 테마가 바로잡히기 전에 잠깐 흰색 화면이 나타납니다.

해결 방법은 다른 코드보다 먼저 동기적으로 실행되는 인라인 스크립트를 document head에 배치하는 것입니다. 이 스크립트는 즉시 localStorage를 읽고 document.documentElement에 data-theme을 설정합니다. 차단 스크립트이므로 브라우저는 콘텐츠를 그리기 전에 특성을 적용합니다.

비동기 또는 지연 스크립트는 HTML이 파싱된 후, 경우에 따라 첫 번째 화면이 그려진 후에 실행됩니다. 그러면 애초의 목적을 달성할 수 없습니다. 차단 인라인 스크립트에는 async나 defer 특성이 없어야 하며 외부 파일에서 불러와서도 안 됩니다. 성능 비용을 최소화하려면 스크립트는 매우 작아야 합니다.

차단 스크립트는 최소한으로 구성됩니다. localStorage.getItem('theme')을 읽고, 대체 방법으로 window.matchMedia('(prefers-color-scheme: dark)').matches를 확인한 다음 document.documentElement.setAttribute('data-theme', theme)을 호출합니다. 비공개 브라우징에서 localStorage를 사용할 수 없는 경우에 대비해 예외 처리 블록으로 감싸십시오.

Next.js에서는 _document.js 내부에서 next/script의 Script 컴포넌트를 strategy="beforeInteractive"와 함께 사용하십시오. beforeInteractive 전략은 페이지의 JavaScript가 실행되기 전에 스크립트를 페이지 HTML에 삽입하므로, Next.js 빌드 과정에서 동일한 차단 동작을 구현합니다.

Vite 또는 CRA 프로젝트에서는 index.html을 직접 수정하고 다른 스크립트보다 앞선 head에 인라인 스크립트 태그를 배치하십시오. index.html은 브라우저의 진입점이므로 스크립트가 React가 시작되기 전에 실행됩니다. 100바이트 미만을 유지할 수 있도록 간결하게 작성하십시오.

서버에서 렌더링되는 앱에서는 서버가 요청과 함께 전송된 쿠키에서 테마를 읽을 수 있습니다. 그런 다음 서버는 브라우저로 보내기 전에 렌더링된 HTML에 data-theme을 설정합니다. 올바른 테마가 HTML의 첫 바이트부터 포함되므로 클라이언트에서 잘못된 테마가 잠깐 나타나는 현상을 완전히 피할 수 있습니다.

전체 흐름은 다음과 같습니다. 브라우저가 HTML을 다운로드하고, 파서가 차단 인라인 스크립트를 만나며, 스크립트가 localStorage를 읽고 data-theme을 설정합니다. 그런 다음 파서가 계속 진행하고, 페이지가 올바른 테마로 그려지며, React가 하이드레이션되어 localStorage에서 동일한 테마를 가져옵니다. 사용자는 시작부터 일관된 하나의 테마를 보게 됩니다.

해결 방법이 제대로 작동하는지 확인하려면 Chrome DevTools를 열고 Network 탭으로 이동한 다음 연결 속도를 느린 3G로 제한하십시오. 페이지를 새로고침하십시오. 로드 중에 테마가 바뀐다면 깜박임이 해결되지 않은 것입니다. 차단 스크립트가 있으면 느린 연결에서도 첫 화면부터 올바른 테마가 표시되어야 합니다.

React의 초기 상태 기본값이 밝은 테마인데 차단 스크립트가 하이드레이션 전에 어두운 테마를 설정했다면, React가 하이드레이션 불일치 경고를 표시할 수 있습니다. 이를 피하려면 초기 렌더링 중에도 localStorage를 읽어 React 테마 상태를 초기화하십시오. 그러면 React가 렌더링한 HTML이 차단 스크립트가 설정한 DOM 상태와 일치합니다.

Storybook과 테스트 환경에서는 index.html을 로드하지 않으므로 차단 스크립트가 실행되지 않습니다. 이러한 환경에서 기본 data-theme 특성을 적용하는 데코레이터나 테스트 설정을 제공하십시오. 이렇게 하면 컴포넌트를 격리하여 개발할 때 혼란스러운 시각적 불일치를 방지할 수 있습니다.

잘못된 테마가 잠깐 나타나는 현상을 방지하려면 문서 head에 어떤 유형의 스크립트를 사용해야 합니까?

어떤 화면도 그려지기 전에 localStorage를 읽고 data-theme을 설정하는 작은 차단 인라인 스크립트를 문서 head에 삽입하여 잘못된 테마가 잠깐 나타나는 현상을 방지하십시오. Next.js에서는 strategy="beforeInteractive"를 사용하고, Vite/CRA에서는 index.html에 직접 추가하십시오. SSR 앱에서는 쿠키를 읽어 서버에서 테마를 설정할 수 있습니다.