在 SSR React 應用程式中設定主題

想像一下，造訪一個可以無縫適應您的偏好的網站，輕鬆在淺色、深色和基於系統的主題之間切換。

本文是我關於使用 React 進行 SSR 的系列文章的繼續。在基礎知識文章中，我們探索了生產就緒的配置，而在先進技術中，我們解決了水合錯誤等挑戰。現在，我們將更進一步，實施與 SSR 無縫整合的強大主題支援。

目錄

• 主題和SSR
• 執行
  • 安裝依賴項
  • 將 cookie 新增至伺服器建置
  • 在伺服器上套用主題
  • 處理客戶端上的主題
• 結論

主題和 SSR

主要問題是初始閃現不正確的主題(FOIT)。

本質上，主題只是改變 CSS 變數。在大多數情況下，您將使用三個主題：

• Light：預設的 CSS 變數集。
• 深色：當 時應用。標籤的類別為 dark。
• 系統：依照使用者的系統偏好自動切換，使用（prefers-color-scheme：dark） 媒體查詢以確定主題應該是深色還是淺色。

預設情況下，伺服器會渲染淺色主題的 HTML 並將其傳送到瀏覽器。如果用戶更喜歡深色主題，他們會在第一頁載入時看到明顯的主題更改，這會破壞用戶體驗。

解決這個問題主要有兩種方法：

• 新增一個在伺服器上的 HTML 中標記並在客戶端動態設定類別。
• 使用cookie來儲存使用者的主題偏好並在伺服器上設定類別。

第一個解決方案是下一個主題包的工作原理（2025 年 1 月）。在本文中，您將實現基於 cookie 的方法，以確保 SSR 應用程式中的無縫主題處理。

執行

要實現主題，您將使用兩個 cookie：

1. serverTheme - 用於將正確的類別應用於 標籤。
2. clientTheme - 用於處理水合錯誤。

客戶端始終設定這兩個 cookie，確保伺服器可以在下一個請求時正確呈現適當的主題。

本指南是基於上一篇文章中介紹的概念，建立生產就緒的 SSR React 應用程式，您可以在底部找到連結。為簡單起見，此處未建立共享常數和類型，但您可以在範例儲存庫中找到它們的實作。

安裝依賴項

安裝 cookie 處理所需的軟體套件：

pnpm add cookie js-cookie

js-cookie 的安裝類型：

pnpm add -D @types/js-cookie

如果你的應用程式中沒有使用react-router，你可以使用cookie套件作為devDependency。

將 cookie 新增到伺服器建置中

更新你的 tsup 設定檔：

// ./tsup.config.ts
import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['server'],
  outDir: 'dist/server',
  target: 'node22',
  format: ['cjs'],
  clean: true,
  minify: true,
  external: ['lightningcss', 'esbuild', 'vite'],
  noExternal: [
    'express',
    'sirv',
    'compression',
    'cookie', // Include the cookie in the server build
  ],
})

在伺服器上套用主題

定義主題常數

// ./server/constants.ts
export const CLIENT_THEME_COOKIE_KEY = 'clientTheme'
export const SERVER_THEME_COOKIE_KEY = 'serverTheme'

export enum Theme {
  Light = 'light',
  Dark = 'dark',
  System = 'system'
}

將主題類別套用到標籤

建立一個實用函數以將正確的主題類別應用到 中基於伺服器主題 cookie 的標籤：

// ./server/lib/applyServerTheme.ts
import { parse } from 'cookie'
import { Request } from 'express'
import { SERVER_THEME_COOKIE_KEY, Theme } from '../constants'

export function applyServerTheme(req: Request, html: string): string {
  const cookies = parse(req.headers.cookie || '')
  const theme = cookies?.[SERVER_THEME_COOKIE_KEY]

  if (theme === Theme.Dark) {
    return html.replace('', `



<h4>
  
  
  Retrieve the Client Theme Cookie
</h4>

<p>Create a utility function to retrieve the clientTheme cookie<br>
</p>

<pre class="brush:php;toolbar:false">// ./server/getClientTheme.ts
import { parse } from 'cookie'
import { Request } from 'express'
import { CLIENT_THEME_COOKIE_KEY, Theme } from '../constants'

export function getClientTheme(req: Request) {
  const cookies = parse(req.headers.cookie || '')

  return cookies?.[CLIENT_THEME_COOKIE_KEY] as Theme | undefined
}

更新主題的伺服器配置

開發配置：

// ./server/dev.ts
import fs from 'fs'
import path from 'path'
import { Application } from 'express'
import { HTML_KEY } from './constants'
import { applyServerTheme } from './lib/applyServerTheme'
import { getClientTheme } from './lib/getClientTheme'

const HTML_PATH = path.resolve(process.cwd(), 'index.html')
const ENTRY_SERVER_PATH = path.resolve(process.cwd(), 'src/entry-server.tsx')

export async function setupDev(app: Application) {
  const vite = await (
    await import('vite')
  ).createServer({
    root: process.cwd(),
    server: { middlewareMode: true },
    appType: 'custom',
  })

  app.use(vite.middlewares)

  app.get('*', async (req, res, next) => {
    try {
      let html = fs.readFileSync(HTML_PATH, 'utf-8')
      html = await vite.transformIndexHtml(req.originalUrl, html)

      const { render } = await vite.ssrLoadModule(ENTRY_SERVER_PATH)
      // send Client Theme from cookie to render
      const appHtml = await render(getClientTheme(req))

      // Apply Server theme on template html
      html = applyServerTheme(req, html)
      html = html.replace(HTML_KEY, appHtml)

      res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
    } catch (e) {
      vite.ssrFixStacktrace(e as Error)
      console.error((e as Error).stack)
      next(e)
    }
  })
}

生產配置：

// ./server/prod.ts
import fs from 'fs'
import path from 'path'
import compression from 'compression'
import { Application } from 'express'
import sirv from 'sirv'
import { HTML_KEY } from './constants'
import { applyServerTheme } from './lib/applyServerTheme'
import { getClientTheme } from './lib/getClientTheme'

const CLIENT_PATH = path.resolve(process.cwd(), 'dist/client')
const HTML_PATH = path.resolve(process.cwd(), 'dist/client/index.html')
const ENTRY_SERVER_PATH = path.resolve(process.cwd(), 'dist/ssr/entry-server.js')

export async function setupProd(app: Application) {
  app.use(compression())
  app.use(sirv(CLIENT_PATH, { extensions: [] }))

  app.get('*', async (req, res, next) => {
    try {
      let html = fs.readFileSync(HTML_PATH, 'utf-8')

      const { render } = await import(ENTRY_SERVER_PATH)
      // send Client Theme from cookie to render
      const appHtml = await render(getClientTheme(req))

      // Apply Server theme on template html
      html = applyServerTheme(req, html)
      html = html.replace(HTML_KEY, appHtml)

      res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
    } catch (e) {
      console.error((e as Error).stack)
      next(e)
    }
  })
}

處理客戶端上的主題

定義常數

複製常數供客戶端使用或將它們移至共用資料夾

// ./src/constants.ts
export const SSR = import.meta.env.SSR

export const CLIENT_THEME_COOKIE_KEY = 'clientTheme'
export const SERVER_THEME_COOKIE_KEY = 'serverTheme'

export enum Theme {
  Light = 'light',
  Dark = 'dark',
  System = 'system',
}

建立主題上下文

設定React上下文來管理主題狀態並提供主題管理方法：

// ./src/theme/context.ts
import { createContext, useContext } from 'react'
import { Theme } from '../constants'

export type ThemeContextState = {
  theme: Theme
  setTheme: (theme: Theme) => void
}

export const ThemeContext = createContext<themecontextstate>({
  theme: Theme.System,
  setTheme: () => null,
})

export const useThemeContext = () => useContext(ThemeContext)
</themecontextstate>

實施主題實用程序

// ./src/theme/lib.ts
import Cookies from 'js-cookie'
import { CLIENT_THEME_COOKIE_KEY, SERVER_THEME_COOKIE_KEY, SSR, Theme } from '../constants'

// Resolve the system theme using the `prefers-color-scheme` media query
export function resolveSystemTheme() {
  if (SSR) return Theme.Light
  return window.matchMedia('(prefers-color-scheme: dark)').matches ? Theme.Dark : Theme.Light
}

// Update the theme cookies and set appropriate class to 
export function updateTheme(theme: Theme) {
  if (SSR) return

  const resolvedTheme = theme === Theme.System ? resolveSystemTheme() : theme

  Cookies.set(CLIENT_THEME_COOKIE_KEY, theme)
  Cookies.set(SERVER_THEME_COOKIE_KEY, resolvedTheme)

  window.document.documentElement.classList.toggle('dark', resolvedTheme === Theme.Dark)
}

// Get the default theme from cookies
export function getDefaultTheme(): Theme {
  if (SSR) return Theme.System
  const theme = (Cookies.get(CLIENT_THEME_COOKIE_KEY) as Theme) || Theme.System

  updateTheme(theme)
  return theme
}

創建主題提供者

// ./src/theme/Provider.tsx
import { PropsWithChildren, useState } from 'react'
import { Theme } from '../constants'
import { ThemeContext } from './context'
import { getDefaultTheme, updateTheme } from './lib'

type Props = PropsWithChildren & {
  defaultTheme?: Theme // Handle theme for SSR
}

export function ThemeProvider({ children, defaultTheme }: Props) {
  const [theme, setTheme] = useState<theme>(defaultTheme || getDefaultTheme())

  const handleSetTheme = (theme: Theme) => {
    setTheme(theme)
    updateTheme(theme)
  }

  return <themecontext value="{{" theme settheme: handlesettheme>{children}</themecontext>
}
</theme>

// ./src/theme/index.ts
export { ThemeProvider } from './Provider'
export { useThemeContext } from './context'

在元件中使用主題上下文

// ./src/App.tsx
import reactLogo from './assets/react.svg'
import viteLogo from '/vite.svg'
import Card from './Card'
import { Theme } from './constants'
import { ThemeProvider } from './theme'

import './App.css'

// Theme from Server Entry
type AppProps = {
  theme?: Theme
}

function App({ theme }: AppProps) {
  return (
    <themeprovider defaulttheme="{theme}">
      <div>
        <a href="https://vite.dev" target="_blank" rel="noreferrer">
          <img src="%7BviteLogo%7D" classname="logo" alt="Vite logo">
        </a>
        <a href="https://react.dev" target="_blank" rel="noreferrer">
          <img src="%7BreactLogo%7D" classname="logo react" alt="React logo">
        </a>
      </div>
      <h1 id="Vite-React">Vite + React</h1>
      <card></card>
      <p classname="read-the-docs">Click on the Vite and React logos to learn more</p>
    </themeprovider>
  )
}

export default App

建立卡片組件

// ./src/Card.tsx
import { useState } from 'react'
import { Theme } from './constants'
import { useThemeContext } from './theme'

function Card() {
  const { theme, setTheme } = useThemeContext()
  const [count, setCount] = useState(0)

  return (
    <div classname="card">
      <button onclick="{()"> setCount((count) => count + 1)}>count is {count}</button>
      <p>
        Edit <code>src/App.tsx</code> and save to test HMR
      </p>
      <div>
        Themes:{' '}
        <select value="{theme}" onchange="{(event)"> setTheme(event.target.value as Theme)}>
          <option value="{Theme.System}">System</option>
          <option value="{Theme.Light}">Light</option>
          <option value="{Theme.Dark}">Dark</option>
        </select>
      </div>
    </div>
  )
}

export default Card

解決水合錯誤

將主題傳遞給伺服器渲染方法，以確保伺服器產生的 HTML 與客戶端渲染相符：

import { renderToString } from 'react-dom/server'
import App from './App'
import { Theme } from './constants'

export function render(theme: Theme) {
  return renderToString(<app theme="{theme}"></app>)
}

新增樣式

:root {
    color: #242424;
    background-color: rgba(255, 255, 255, 0.87);
}

:root.dark {
    color: rgba(255, 255, 255, 0.87);
    background-color: #242424;
}

結論

在本文中，我們解決了在 SSR React 應用程式中實現無縫主題的挑戰。透過使用 cookie 並整合客戶端和伺服器端邏輯，我們創建了一個強大的系統，支援淺色、深色和基於系統的主題，而不會出現水合作用錯誤或使用者體驗中斷。

探索程式碼

• 範例：react-ssr-themes-example
• 以SSR落地：專業落地

相關文章

這是我的 React SSR 系列的一部分。更多文章敬請期待！

• 建構生產就緒的 SSR React 應用程式
• 使用串流和動態資料的進階 React SSR 技術
• 在 SSR React 應用程式中設定主題

保持聯繫

我總是樂於接受回饋、合作或討論技術想法 - 請隨時與我們聯繫！

• 投資組合：maxh1t.xyz
• 電子郵件：m4xh17@gmail.com

以上是在 SSR React 應用程式中設定主題的詳細內容。更多資訊請關注PHP中文網其他相關文章！