پیاده‌سازی تم روشن و تاریک در Next.js 16 با @wrksz/themes

برنامه‌های مدرن باید تجربه‌ای راحت در هر دو محیط روشن و تاریک ارائه دهند.

مدیریت تم از بیرون ساده به نظر می‌رسد، اما یک پیاده‌سازی کامل نیازمند مدیریت وضعیت تم، تنظیمات سیستم، ذخیره انتخاب کاربر و حل مشکلات hydration است.

در مقاله قبلی، یک سیستم تم را بدون استفاده از وابستگی خارجی پیاده‌سازی کردیم. در این مقاله از @wrksz/themes برای ایجاد یک راهکار تمیزتر و مناسب محیط تولید استفاده می‌کنیم.

چیزی که می‌سازیم

سیستم نهایی از موارد زیر پشتیبانی می‌کند:

• حالت روشن
• حالت تاریک
• تنظیمات سیستم
• ذخیره‌سازی انتخاب تم
• اتصال به Tailwind CSS
• رندر امن SSR

جریان کار:

کاربر تم را تغییر می‌دهد
        |
        v
@wrksz/themes وضعیت را مدیریت می‌کند
        |
        v
کلاس تم HTML تغییر می‌کند
        |
        v
متغیرهای CSS به‌روزرسانی می‌شوند
        |
        v
رابط کاربری برنامه تغییر می‌کند

تکنولوژی‌های پروژه

• Next.js 16 App Router
• React 19
• TypeScript
• Tailwind CSS v4
• @wrksz/themes

نصب

bun add lucide-react @wrksz/themes

افزودن ThemeProvider

import { ThemeProvider } from '@wrksz/themes/next';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

ساخت Theme Toggle

'use client';
 
import { useTheme } from '@wrksz/themes/client';
import { Moon, Sun } from 'lucide-react';
 
export function ThemeToggle() {
  const { resolvedTheme, setTheme } = useTheme();
 
  const isDark = resolvedTheme === 'dark';
 
  return (
    <button
      onClick={() => setTheme(isDark ? 'light' : 'dark')}
      className="hover:bg-muted rounded-full border p-3 transition"
      aria-label="Theme toggle"
    >
      {isDark ? <Moon size={20} /> : <Sun size={20} />}
    </button>
  );
}

تم‌های موجود

برنامه از موارد زیر پشتیبانی می‌کند:

• light
• dark
• system

حالت system از مقدار زیر پیروی می‌کند:

prefers-color-scheme

اتصال Tailwind CSS

تم فعال از طریق کلاس HTML اعمال می‌شود:

<html class="dark"></html>

متغیرهای CSS می‌توانند رنگ‌های تم را تعریف کنند:

:root {
  --background: #ffffff;
}
 
.dark {
  --background: #10131c;
}

کامپوننت‌ها از رنگ‌های معنایی استفاده می‌کنند:

<div className="bg-background text-foreground">Content</div>

مدیریت Hydration

سیستم‌های تم می‌توانند باعث خطای hydration mismatch شوند، زیرا سرور از تنظیمات مرورگر کاربر اطلاع ندارد.

ممکن است خروجی اولیه سرور و کلاینت متفاوت باشد.

@wrksz/themes یکپارچه‌سازی Next.js را برای ساده‌تر کردن این فرآیند فراهم می‌کند.

مقایسه پیاده‌سازی Native و @wrksz/themes

پیاده‌سازی Native برای یادگیری مفاهیم زیر مفید است:

• React Context
• localStorage
• matchMedia
• DOM manipulation
• hydration handling

استفاده از @wrksz/themes مزایای زیر را دارد:

• کد کمتر
• API ساده‌تر
• نگهداری آسان‌تر
• مناسب برای محیط تولید

نتیجه‌گیری

درک نحوه کار داخلی سیستم‌های تم اهمیت زیادی دارد.

با این حال، برنامه‌های تولیدی معمولا از راهکارهای اختصاصی برای ساده‌تر شدن توسعه استفاده می‌کنند.

@wrksz/themes یک روش ساده و قابل نگهداری برای افزودن تم روشن، تاریک و سیستم به برنامه‌های مدرن Next.js ارائه می‌دهد.