I was tired of next-themes being abandoned, so I built a drop-in replacement

Jakub — Mon, 30 Mar 2026 17:07:48 +0000

next-themes has 22 million weekly downloads. It hasn't had a release in over a year. There are 43 open issues and 16 unmerged PRs sitting there, including React 19 compatibility bugs that affect every project upgrading to Next.js 16.

I got tired of waiting. So I built @wrksz/themes.

The problem with next-themes

When Next.js 16 and React 19 dropped, projects started hitting a wall. The most common issues:

React 19 script warning - next-themes renders an inline <script> inside a Client Component. React 19 started warning about this explicitly:

Encountered a script tag while rendering React component.
Scripts inside React components are never executed when rendering on the client.

Stale theme with cacheComponents - next-themes uses useState + useContext, which causes stale theme values when React's Activity or cacheComponents suspend and resume a subtree. Your theme gets stuck.

__name minification bug - production builds that minify function names break next-themes internals silently.

Multi-class themes leave stale classes - if you map a theme to multiple CSS classes like "dark high-contrast", switching away from it leaves high-contrast stuck on the DOM forever.

All of these have been sitting open for months with no movement.

What I built

@wrksz/themes is a drop-in replacement. Migrating is literally one import change:

npm uninstall next-themes
npm install @wrksz/themes

// before
import { ThemeProvider } from "next-themes";

// after
import { ThemeProvider } from "@wrksz/themes/next";

That's it. The API is identical.

What's fixed

Every known bug from next-themes is fixed:

React 19 script warning - fixed by using useServerInsertedHTML to inject the script outside the React component tree
Stale theme with cacheComponents - fixed by using useSyncExternalStore with a per-instance store
__name minification bug - fixed
Multi-class theme removal - fixed with proper flatMap + split before removing classes

What's new

Beyond fixes, I added features that were frequently requested but never implemented:

Cookie storage with zero-flash SSR - the biggest one. With storage="cookie", the Next.js provider reads the cookie server-side automatically. No flash, no suppressHydrationWarning hacks, no boilerplate:

// app/layout.tsx
import { ThemeProvider } from "@wrksz/themes/next";

export default async function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider storage="cookie" defaultTheme="dark">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Generic types - full TypeScript safety with your custom theme names:

type AppTheme = "light" | "dark" | "high-contrast";

const { theme, setTheme } = useTheme<AppTheme>();
// theme: AppTheme | "system" | undefined
// setTheme: (theme: AppTheme | "system") => void

Nested providers - each provider gets its own independent store. You can scope themes to specific sections of your app:

<ThemeProvider forcedTheme="dark" target="#landing" storage="none">
  <div id="landing">...</div>
</ThemeProvider>

ThemedImage - a built-in component that solves the hydration mismatch problem with theme-aware images:

import { ThemedImage } from "@wrksz/themes/client";

<ThemedImage
  src={{ light: "/logo-light.png", dark: "/logo-dark.png" }}
  alt="Logo"
  width={200}
  height={50}
/>

useThemeValue - returns a value from a map based on the current theme:

const label = useThemeValue({ light: "Switch to dark", dark: "Switch to light" });

sessionStorage, storage: "none" - more storage options for different use cases.

meta theme-color - updates <meta name="theme-color"> automatically for Safari and PWAs.

Comparison table

	next-themes	@wrksz/themes
React 19 script warning	Yes	Fixed
`__name` minification bug	Yes	Fixed
Stale theme with cacheComponents	Yes	Fixed
Multi-class removal bug	Yes	Fixed
Nested providers	No	Yes
sessionStorage support	No	Yes
Cookie storage (zero-flash SSR)	No	Yes
Disable storage	No	Yes
meta theme-color	No	Yes
Server-provided theme	No	Yes
Generic TypeScript types	No	Yes
Zero runtime dependencies	Yes	Yes

Try it

bun add @wrksz/themes
# or
npm install @wrksz/themes

Docs: themes.wrksz.dev
GitHub: github.com/jakubwarkusz/themes

Migration guide: themes.wrksz.dev/docs/migration