Система тем приложения

Руководство по переключению тем (light/dark) без мигания: Vite — React Context + inline-скрипт, Next.js — next-themes.

Архитектура управления темой

Преимущество: Изоляция логики темы от бизнес-компонентов. Автоматическое сохранение выбора пользователя и отсутствие 'мигания' при загрузке.

Структура файлов Темизации

Расположение и Соглашения

Провайдер:
Находится в src/app/providers/theme/. Отвечает за глобальную инициализацию.
Shared Logic:
Контекст, хуки и UI-компонент выносятся в shared/, так как они переиспользуемы.

01Типы и Интерфейсы

Определяем допустимые значения темы (light, dark) и структуру контекста для управления состоянием.

shared/ui/layout/theme-toggle/model/theme.types.ts

export type TTheme = "light" | "dark";

export interface IThemeContextType {
    theme: TTheme;
    toggleTheme: () => void;
}

02React Context

Создаем канал передачи данных темы через дерево компонентов без использования пропсов.

shared/ui/layout/theme-toggle/model/theme.context.ts

import { createContext } from "react";
import { IThemeContextType } from "./theme.types";

export const ThemeContext = createContext<IThemeContextType | undefined>(undefined);

03Кастомный Хук

Инкапсулируем логику доступа к контексту в удобном хуке useTheme с проверкой на наличие провайдера.

shared/ui/layout/theme-toggle/model/use-theme.ts

import { useContext } from "react";
import { ThemeContext } from "./theme.context";

export const useTheme = () => {
    const context = useContext(ThemeContext);
    if (!context) {
        throw new Error("useTheme must be used within a ThemeProvider");
    }
    return context;
};

04Theme Provider

Inline-скрипт в index.html ставит класс на html до первой отрисовки (сохранённый выбор или prefers-color-scheme). Провайдер берёт этот класс как начальное состояние, следует за системной темой, пока пользователь не выбрал свою, и сохраняет выбор в localStorage. На Next.js вместо этого — next-themes.

index.html

<script>
  (function () {
    try {
      var saved = localStorage.getItem("theme");
      var system = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
      document.documentElement.classList.add(saved === "light" || saved === "dark" ? saved : system);
    } catch (e) {
      document.documentElement.classList.add("light");
    }
  })();
</script>

app/providers/theme/theme.provider.tsx

import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
import { type TTheme, ThemeContext } from "@/shared/ui/layout/theme-toggle";

const STORAGE_KEY = "theme";
const DARK_QUERY = "(prefers-color-scheme: dark)";

const getSystemTheme = (): TTheme =>
    window.matchMedia(DARK_QUERY).matches ? "dark" : "light";

/** Класс уже выставлен inline-скриптом до первой отрисовки */
const getInitialTheme = (): TTheme =>
    document.documentElement.classList.contains("dark") ? "dark" : "light";

export const ThemeProvider = ({ children }: { children: ReactNode }) => {
    const [theme, setTheme] = useState<TTheme>(getInitialTheme);

    // Следуем за системной темой, пока нет явного выбора
    useEffect(() => {
        const media = window.matchMedia(DARK_QUERY);
        const onChange = () => {
            if (!localStorage.getItem(STORAGE_KEY)) setTheme(getSystemTheme());
        };
        media.addEventListener("change", onChange);
        return () => media.removeEventListener("change", onChange);
    }, []);

    useEffect(() => {
        const root = document.documentElement;
        root.classList.remove("light", "dark");
        root.classList.add(theme);
    }, [theme]);

    const toggleTheme = useCallback(() => {
        setTheme((prev) => {
            const next = prev === "light" ? "dark" : "light";
            localStorage.setItem(STORAGE_KEY, next);
            return next;
        });
    }, []);

    const value = useMemo(() => ({ theme, toggleTheme }), [theme, toggleTheme]);

    return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
};

// Next.js: вместо своего провайдера — next-themes
// (attribute="class", defaultTheme="system", enableSystem, <html suppressHydrationWarning>)

05HOC для инициализации

HOC withTheme оборачивает корневой компонент в ThemeProvider — тема подключается одной строкой: export default withTheme(App).

app/providers/theme/with-theme.tsx

import type { ComponentType, FC } from "react";
import { ThemeProvider } from "./theme.provider";

/** Подключение темы одной строкой: export default withTheme(App) */
export const withTheme = <P extends object>(Component: ComponentType<P>): FC<P> => {
    const WithTheme: FC<P> = (props) => (
        <ThemeProvider>
            <Component {...props} />
        </ThemeProvider>
    );

    WithTheme.displayName = `withTheme(${Component.displayName || Component.name || "Component"})`;

    return WithTheme;
};

06UI Компонент (Toggle)

Создаем кнопку-переключатель, которая использует хук useTheme для смены визуального стейта.

shared/ui/layout/theme-toggle/ui/theme-toggle.tsx

import { Moon, Sun } from "lucide-react";
import { Button } from "@/shared/ui";
import { useTheme } from "../model";

export const ThemeToggle = () => {
    const { theme, toggleTheme } = useTheme();

    return (
        <Button onClick={toggleTheme} variant="outline" size="sm">
            {theme === "light" ? <Moon size={16} /> : <Sun size={16} />}
        </Button>
    );
};