@wrksz/themes
v1.0.0
Published
A modern, fully-featured theme management library for Next.js
Readme
@wrksz/themes
Modern theme management for Next.js and React. It keeps the next-themes style API, adds typed helpers, and fixes React 19 / Next.js App Router edge cases around inline scripts, server themes, cookies, and hydration.
bun add @wrksz/themes
# or
npm install @wrksz/themesSetup
Use the Next.js entry in app/layout.tsx:
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>
);
}Use client hooks from the client entry:
"use client";
import { useTheme } from "@wrksz/themes/client";
export function ThemeToggle() {
const { resolvedTheme, setTheme } = useTheme();
return (
<button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
Toggle theme
</button>
);
}Highlights
- React 19 friendly Next.js provider using
useServerInsertedHTML. localStorage,sessionStorage,cookie,hybrid, and disabled storage modes.- Zero-flash SSR when using cookie storage with
@wrksz/themes/next. initialTheme,themeColor, nested providers, scoped targets, and multi-class theme values.- Typed
useTheme,useThemeValue,useThemeEffect,ThemedImage, andcreateThemes. - Fine-grained client subpath exports for smaller app bundles.
- No runtime dependencies.
Cookie SSR
import { ThemeProvider } from "@wrksz/themes/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider storage="cookie" defaultTheme="dark" disableTransitionOnChange>
{children}
</ThemeProvider>
</body>
</html>
);
}Import Paths
import { ThemeProvider, getTheme } from "@wrksz/themes/next";
import {
ClientThemeProvider,
ThemedImage,
createThemes,
useTheme,
useThemeEffect,
useThemeValue,
} from "@wrksz/themes/client";Fine-grained client modules are also available:
import { useTheme } from "@wrksz/themes/client/use-theme";
import { useThemeValue } from "@wrksz/themes/client/use-theme-value";
import { useThemeEffect } from "@wrksz/themes/client/use-theme-effect";
import { ThemedImage } from "@wrksz/themes/client/themed-image";
import { ClientThemeProvider } from "@wrksz/themes/client/provider";
import { createThemes } from "@wrksz/themes/client/create-themes";Full API docs and examples live at themes.wrksz.dev.
License
MIT