Agent integration guide

This guide covers @wrksz/themes 2.x. Check your installed version and type declarations; online docs may include APIs from a newer release.

For a shorter reference, ask your agent to read node_modules/@wrksz/themes/AGENTS.md. Some agents skip instructions inside dependencies.

Plain Markdown · Documentation index · Full documentation

Imports

The package root exports the client provider and factory without a bootstrap script. For Next.js, use /next in server layouts. That entry also exports server-only getTheme, so client modules must use /client or /next/create-themes.

Next.js layout and toggle

Keep the root layout on the server and leave existing auth or query providers in place.

import type { ReactNode } from "react";
import { ThemeProvider } from "@wrksz/themes/next";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class">{children}</ThemeProvider>
      </body>
    </html>
  );
}

"use client";

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

export function ThemeToggle() {
  const { resolvedTheme, forcedTheme, setTheme } = useTheme();
  return (
    <button
      type="button"
      disabled={!resolvedTheme || !!forcedTheme}
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
    >
      Toggle theme
    </button>
  );
}

The button renders the same label before hydration. For icons or text that depend on the theme, render a placeholder until useHydrated() returns true. suppressHydrationWarning on html covers only that element's attribute changes.

The default provider uses class, localStorage, key theme, light/dark themes and system detection. CSS must match the chosen attribute; the provider does not supply styles.

Typed configuration

"use client";

import { createThemes } from "@wrksz/themes/next/create-themes";

export const { NextThemeProvider, useTheme, useThemeValue } = createThemes({
  themes: ["light", "dark", "high-contrast"] as const,
  attribute: "class",
  defaultTheme: "system",
});

Import the provider and hooks from this same module. Each factory creates a separate context, so global hooks cannot read its provider. Call createThemes once at module scope.

Use the extended provider for systemThemeMap, themeRoot or enableSameDocumentSync; the factory does not accept these options. Custom system names such as paper/midnight need systemThemeMap on the extended provider, or enableSystem={false} with an explicit default.

Storage and server rendering

The Next.js provider applies the stored theme in the browser without calling cookies() on the server. Choose storage based on where you need the preference:

• localStorage retains the preference and synchronizes browser tabs.
• sessionStorage retains it for the tab; the library does not subscribe to cross-tab updates.
• cookie makes it readable by the server but does not synchronize tabs.
• hybrid reads cookies first and mirrors writes to localStorage for cross-tab updates.
• none avoids persistence, useful for independent widgets or forced themes.

getTheme() reads cookies, not localStorage, and cannot determine the browser's system preference. It can return "system", even with defaultTheme: "light" when the stored cookie contains "system". Do not copy an unresolved selection directly into html.className.

If server-rendered content needs the theme, read the cookie per request and pass the selection as initialTheme. With Cache Components, keep that read inside the app's request-time boundary. See getTheme and server themes.

In other SSR frameworks, render ThemeScript before theme-dependent content and match its themes, attribute, value, storage, storageKey and defaults to the client provider. See framework integration.

Antipatterns

Changing initialTheme or storageKey does not reload stored state. To initialize again after switching accounts or workspaces, remount the provider.

Troubleshooting

With CSP, pass the request's script nonce to authorize the bootstrap. It does not need unsafe-eval. Transition suppression also creates a style element; check style-src separately because a script nonce does not authorize styles.

Migration and verification

Follow the migration guide before removing next-themes.

Run the app's type check and production build. Test cold loads with empty and saved storage, then reload and use browser back/forward. Exercise the system option and any forced or scoped themes. For localStorage/hybrid, test a second tab; for extended same-document sync, test two providers.

Report the checks you ran in the consuming app, including any CSS, CSP or hydration issues that remain.