V2 to V3

Incremental sequence

pnpm dlx shadcn@latest add @poyraz/poyraz-theme @poyraz/poyraz-utils @poyraz/poyraz-recipes

pnpm dlx shadcn@latest add @poyraz/button @poyraz/input @poyraz/card

pnpm dlx shadcn@latest add @poyraz/dialog @poyraz/select @poyraz/dropdown-menu @poyraz/tabs

pnpm dlx shadcn@latest add @poyraz/navbar @poyraz/sidebar @poyraz/footer @poyraz/dashboard-shell-block

Component mapping

This mapping is only required for the source-ownership route. Install the registry item first, then replace that component's package import with the local target.

Prop mapping

Variant changes

Token mapping

Source route: remove V2 runtime theme objects

The registry theme owns variables. A provider-independent application only needs to set the selector consumed by the preset.

export function setColorTheme(theme: "light" | "dark") {
  document.documentElement.dataset.poyrazTheme = theme;
  localStorage.setItem("color-theme", theme);
}

Next.js with next-themes

"use client";

import { ThemeProvider } from "next-themes";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="data-poyraz-theme" defaultTheme="system" enableSystem>
      {children}
    </ThemeProvider>
  );
}

Add suppressHydrationWarning to the root html element and mount theme-dependent controls on the client.

Audit and safe codemod

pnpm migration:audit src app components
pnpm migration:tokens src app components
pnpm migration:codemod -- src app components
pnpm migration:codemod --write -- src app components

The codemod changes named imports only when the local registry target already exists. It does not rewrite props, compositions, namespace imports or consumer component files.

Overwrite and rollback policy

1. Commit before each registry install and never enable global overwrite.
2. Keep consumer customization in a separate commit from upstream source updates.
3. Rollback the component-specific commit and restore its pinned V2 import.
4. Remove registry dependencies only after checking migrated dependents.
5. Re-run typecheck, production build, keyboard and visual checks.