fix(upgrade): add package replacement for @clerk/themes → @clerk/ui (#7932)

Author: jacekradko

.changeset/rude-pans-study.md

@@ -0,0 +1,5 @@
+---
+"@clerk/upgrade": patch
+---
+
+fix(upgrade): add package replacement for @clerk/themes → @clerk/ui

packages/upgrade/src/__tests__/fixtures/nextjs-v6-with-themes/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "test-nextjs-v6-with-themes",
+  "version": "1.0.0",
+  "dependencies": {
+    "@clerk/nextjs": "^6.0.0",
+    "@clerk/themes": "^2.0.0",
+    "next": "^14.0.0",
+    "react": "^18.0.0"
+  },
+  "engines": {
+    "node": ">=18.1.0"
+  }
+}

packages/upgrade/src/__tests__/fixtures/nextjs-v6-with-themes/pnpm-lock.yaml

@@ -0,0 +1,10 @@
+import { dark } from '@clerk/themes';
+import { ClerkProvider } from '@clerk/nextjs';
+
+export default function App() {
+  return (
+    <ClerkProvider appearance={{ baseTheme: dark }}>
+      <div>Hello</div>
+    </ClerkProvider>
+  );
+}

packages/upgrade/src/__tests__/fixtures/nextjs-v6-with-themes/src/app.tsx

@@ -317,4 +317,47 @@ describe('CLI Integration', () => {
       expect(result.exitCode).toBe(1);
     });
   });
+
+  describe('Package Replacements', () => {
+    let fixture;
+
+    beforeEach(() => {
+      fixture = createTempFixture('nextjs-v6-with-themes');
+    });
+
+    afterEach(() => {
+      fixture?.cleanup();
+    });
+
+    it('shows replacement message in dry-run mode', async () => {
+      const result = await runCli(['--dir', fixture.path, '--dry-run', '--skip-codemods'], { timeout: 15000 });
+
+      expect(result.stdout).toContain('[dry run]');
+      expect(result.stdout).toContain('@clerk/themes');
+      expect(result.stdout).toContain('@clerk/ui');
+    });
+
+    it('skips replacement when --skip-upgrade is used', async () => {
+      const fs = await import('node:fs');
+      const pkgBefore = fs.readFileSync(path.join(fixture.path, 'package.json'), 'utf8');
+
+      await runCli(['--dir', fixture.path, '--skip-upgrade', '--skip-codemods'], { timeout: 15000 });
+
+      const pkgAfter = fs.readFileSync(path.join(fixture.path, 'package.json'), 'utf8');
+      expect(pkgAfter).toBe(pkgBefore);
+    });
+
+    it('does not show replacement when package is not present', async () => {
+      const noThemesFixture = createTempFixture('nextjs-v6');
+      try {
+        const result = await runCli(['--dir', noThemesFixture.path, '--dry-run', '--skip-codemods'], {
+          timeout: 15000,
+        });
+
+        expect(result.stdout).not.toContain('Would replace');
+      } finally {
+        noThemesFixture.cleanup();
+      }
+    });
+  });
 });

packages/upgrade/src/__tests__/integration/cli.test.js

@@ -27,7 +27,9 @@ import {
 } from './util/detect-sdk.js';
 import {
   detectPackageManager,
+  getInstallCommand,
   getPackageManagerDisplayName,
+  hasPackage,
   removePackage,
   upgradePackage,
 } from './util/package-manager.js';
@@ -245,6 +247,11 @@ async function main() {
     await performUpgrade(sdk, packageManager, config, options);
   }
 
+  // Step 6b: Handle package replacements
+  if (config.packageReplacements?.length > 0 && !options.skipUpgrade) {
+    await performPackageReplacements(packageManager, config, options);
+  }
+
   // Step 7: Run codemods
   if (config.codemods?.length > 0) {
     renderText(`Running ${config.codemods.length} codemod(s)...`, 'blue');
@@ -302,6 +309,49 @@ async function performUpgrade(sdk, packageManager, config, options) {
   }
 }
 
+async function performPackageReplacements(packageManager, config, options) {
+  const replacements = config.packageReplacements;
+  if (!replacements?.length) {
+    return;
+  }
+
+  for (const { from, to } of replacements) {
+    if (!hasPackage(from, options.dir)) {
+      continue;
+    }
+
+    const targetVersion = options.canary ? 'canary' : 'latest';
+
+    if (options.dryRun) {
+      renderText(`[dry run] Would replace ${from} with ${to}@${targetVersion}`, 'yellow');
+      continue;
+    }
+
+    const removeSpinner = createSpinner(`Removing ${from}...`);
+    try {
+      await removePackage(packageManager, from, options.dir);
+      removeSpinner.success(`Removed ${from}`);
+    } catch (error) {
+      removeSpinner.error(`Failed to remove ${from}`);
+      renderError(error.message);
+      renderWarning(`You may need to manually remove ${from} and install ${to}`);
+      continue;
+    }
+
+    const installSpinner = createSpinner(`Installing ${to}@${targetVersion}...`);
+    try {
+      await upgradePackage(packageManager, to, targetVersion, options.dir);
+      installSpinner.success(`Installed ${to}@${targetVersion}`);
+    } catch (error) {
+      installSpinner.error(`Failed to install ${to}`);
+      renderError(error.message);
+      const [cmd, args] = getInstallCommand(packageManager, to, targetVersion, options.dir);
+      renderWarning(`${from} was removed but ${to} could not be installed. Please run: ${cmd} ${args.join(' ')}`);
+      throw new Error(`Package replacement failed: ${from} -> ${to}`);
+    }
+  }
+}
+
 main().catch(error => {
   renderError(error.message);
   process.exit(1);

packages/upgrade/src/cli.js

@@ -139,3 +139,16 @@ export function getPackageManagerDisplayName(packageManager) {
       return 'npm';
   }
 }
+
+export function hasPackage(packageName, cwd) {
+  const pkgPath = path.join(path.resolve(cwd), 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return false;
+  }
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return !!(pkg.dependencies?.[packageName] || pkg.devDependencies?.[packageName]);
+  } catch {
+    return false;
+  }
+}

packages/upgrade/src/util/package-manager.js

@@ -14,3 +14,5 @@ The `createTheme` theme utility has been moved to a new export path. Update your
 ```
 
 Note: The `__experimental_` prefix has been removed from the method since they're now in the `/themes/experimental` subpath.
+
+The `@clerk/themes` package has been replaced by `@clerk/ui`. The upgrade CLI will automatically remove `@clerk/themes` and install `@clerk/ui` in your dependencies.

packages/upgrade/src/versions/core-3/changes/ui-themes-export-path.md

@@ -33,4 +33,5 @@ export default {
     { name: 'transform-satellite-auto-sync', packages: ['nextjs', 'react', 'expo', 'astro', 'tanstack-react-start'] },
     'transform-internal-clerk-js-ui-props',
   ],
+  packageReplacements: [{ from: '@clerk/themes', to: '@clerk/ui' }],
 };

packages/upgrade/src/versions/core-3/index.js

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@clerk/nextjs": "canary",
-    "@clerk/themes": "canary",
+    "@clerk/ui": "canary",
     "@clerk/types": "canary",
     "next": "^15",
     "react": "^19.1.1",