# Migrate Next Themes > Migrate a Next.js App Router project from next-themes to ssr-themes. Use when replacing next-themes providers and hooks, removing mounted theme guards, and choosing between a minimal client-bootstrap migration and a maximal SSR-aware migration. Use when this capability is needed. - Skill: `tomevault-io/migrate-next-themes` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/migrate-next-themes` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/migrate-next-themes/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/migrate-next-themes --- # Migrate `next-themes` to `ssr-themes` Migrate the current project from `next-themes` to `ssr-themes` in place. ## Scope - Support Next.js App Router projects only. - Do not attempt Pages Router migrations. - Preserve the project name, package name, app copy, styling, and theme names unless a file specifically mentions `next-themes` and needs wording updates. - Prefer the smallest correct set of edits. ## Arguments - `$0` is the requested migration mode. - Valid modes are `minimal` and `maximal`. If `$0` is missing or invalid, ask exactly one focused question before editing: "Do you want the minimal or maximal migration? Recommended: minimal. Minimal keeps the migration simple with `themeScript()` and `ThemeProvider` only. Maximal also reads the cookie on the server and uses `registerTheme()` plus `initial` so theme-aware SSR markup is correct on first render." Do not make edits until the user answers that question. ## Preflight Before editing: 1. Confirm the repo uses Next.js App Router by finding an `app/` directory and the current layout/provider wiring. 2. Find all `next-themes` imports and all `useTheme()` call sites. 3. Identify any mounted guards that exist only because `next-themes` theme state is hydration-unsafe. 4. Inspect the current provider config and preserve its theme behavior where possible: - `themes` - `attribute` - `defaultTheme` - `enableSystem` - `enableColorScheme` - custom theme names - theme value mapping - `nonce` and `scriptProps` - forced-theme behavior If the project is Pages Router only, stop and explain that this skill supports App Router only. ## Core migration rules - Remove `next-themes` from dependencies and add `ssr-themes`. - Create a shared `app/theme.ts` file when the app does not already have one. - Use `createTheme(...)` for shared config. - Use `bindTheme(theme)` from `ssr-themes/react`. - Keep `suppressHydrationWarning` on `` when the migration is not maximal, because the SSR markup will not be theme-aware until the client script runs. - Preserve existing bootstrap script attributes such as `nonce` and `data-*` when replacing the old provider-managed script with an explicit Next `