@clerk/upgrade 2.0.0-snapshot.v20251204175016 → 2.0.0-snapshot.v20251208202852

package/dist/__tests__/integration/runner.test.js

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { loadConfig } from '../../config.js';
+import { runScans } from '../../runner.js';
+import { createTempFixture } from '../helpers/create-fixture.js';
+vi.mock('../../render.js', () => ({
+  colors: {
+    reset: '',
+    bold: '',
+    yellow: '',
+    gray: ''
+  },
+  createSpinner: vi.fn(() => ({
+    update: vi.fn(),
+    stop: vi.fn(),
+    success: vi.fn(),
+    error: vi.fn()
+  })),
+  promptText: vi.fn((msg, defaultValue) => defaultValue),
+  renderCodemodResults: vi.fn(),
+  renderText: vi.fn()
+}));
+describe('runScans', () => {
+  let fixture;
+  beforeEach(() => {
+    fixture = createTempFixture('nextjs-v6');
+  });
+  afterEach(() => {
+    fixture?.cleanup();
+  });
+  it('finds patterns in fixture files', async () => {
+    const config = await loadConfig('nextjs', 6);
+    const options = {
+      dir: fixture.path,
+      ignore: []
+    };
+    const results = await runScans(config, 'nextjs', options);
+    expect(Array.isArray(results)).toBe(true);
+  });
+  it('returns empty array when no matchers match', async () => {
+    const config = await loadConfig('nextjs', 6);
+    config.changes = [];
+    const options = {
+      dir: fixture.path,
+      ignore: []
+    };
+    const results = await runScans(config, 'nextjs', options);
+    expect(results).toEqual([]);
+  });
+  it('respects ignore patterns', async () => {
+    const config = await loadConfig('nextjs', 6);
+    const options = {
+      dir: fixture.path,
+      ignore: ['**/src/**']
+    };
+    const results = await runScans(config, 'nextjs', options);
+    expect(Array.isArray(results)).toBe(true);
+  });
+});
+describe('runScans with theme imports', () => {
+  let fixture;
+  beforeEach(() => {
+    fixture = createTempFixture('nextjs-v6');
+  });
+  afterEach(() => {
+    fixture?.cleanup();
+  });
+  it('detects theme imports from @clerk/nextjs/themes', async () => {
+    const config = await loadConfig('nextjs', 6);
+    const options = {
+      dir: fixture.path,
+      ignore: []
+    };
+    const results = await runScans(config, 'nextjs', options);
+    const themeChange = results.find(r => r.title?.includes('Theme') || r.docsAnchor?.includes('theme'));
+    if (themeChange) {
+      expect(themeChange.instances.length).toBeGreaterThan(0);
+    }
+  });
+});

package/dist/cli.js

@@ -1,68 +1,182 @@
 #!/usr/bin/env node
-import { render } from 'ink';
 import meow from 'meow';
-import React from 'react';
-import App from './app.js';
-import sdks from './constants/sdks.js';
+import { getOldPackageName, getTargetPackageName, loadConfig } from './config.js';
+import { createSpinner, promptConfirm, promptSelect, renderComplete, renderConfig, renderError, renderHeader, renderNewline, renderScanResults, renderSuccess, renderText, renderWarning } from './render.js';
+import { runCodemods, runScans } from './runner.js';
+import { detectSdk, getSdkVersion, getSupportedSdks, normalizeSdkName } from './util/detect-sdk.js';
+import { detectPackageManager, getPackageManagerDisplayName, removePackage, upgradePackage } from './util/package-manager.js';
+const isInteractive = process.stdin.isTTY;
 const cli = meow(`
     Usage
-      $ clerk-upgrade
+      $ npx @clerk/upgrade
 
     Options
-      --from             Major version number you're upgrading from
-      --to               Major version number you're upgrading to
-      --sdk              Name of the SDK you're upgrading
-      --dir              Directory you'd like to scan for files
-      --ignore           Any files or directories you'd like to ignore
-      --noWarnings       Do not print warnings, only items that must be fixed
-      --disableTelemetry Do not send anonymous usage telemetry
+      --sdk              Name of the SDK you're upgrading (e.g., nextjs, react)
+      --dir              Directory to scan (defaults to current directory)
+      --glob             Glob pattern for files to transform (defaults to **/*.{js,jsx,ts,tsx,mjs,cjs})
+      --ignore           Directories/files to ignore (can be used multiple times)
+      --dry-run          Show what would be done without making changes
 
     Examples
-      $ clerk-upgrade --sdk=nextjs --dir=src/**
-      $ clerk-upgrade --ignore=**/public/** --ignore=**/dist/**
-      $ clerk-upgrade --from=core-1 --to=core-2
-	`, {
+      $ npx @clerk/upgrade
+      $ npx @clerk/upgrade --sdk=nextjs
+      $ npx @clerk/upgrade --dir=./src --ignore=**/test/**
+      $ npx @clerk/upgrade --dry-run
+
+    Non-interactive mode:
+      When running in CI or piped environments, --sdk is required if it cannot be auto-detected.
+`, {
   importMeta: import.meta,
   flags: {
-    from: {
-      type: 'string'
-    },
-    to: {
+    sdk: {
       type: 'string'
     },
-    sdk: {
+    dir: {
       type: 'string',
-      choices: sdks.map(i => i.value)
+      default: process.cwd()
     },
-    dir: {
-      type: 'string'
+    glob: {
+      type: 'string',
+      default: '**/*.(js|jsx|ts|tsx|mjs|cjs)'
     },
     ignore: {
       type: 'string',
       isMultiple: true
     },
-    yolo: {
-      type: 'boolean'
+    dryRun: {
+      type: 'boolean',
+      default: false
     },
-    noWarnings: {
-      type: 'boolean'
-    },
-    disableTelemetry: {
-      type: 'boolean'
+    skipCodemods: {
+      type: 'boolean',
+      default: false
     }
   }
 });
-render(/*#__PURE__*/React.createElement(App, {
-  dir: cli.flags.dir,
-  disableTelemetry: cli.flags.disableTelemetry,
-  fromVersion: cli.flags.from,
-  ignore: cli.flags.ignore,
-  noWarnings: cli.flags.noWarnings,
-  packageManager: cli.flags.packageManager,
-  sdk: cli.flags.sdk,
-  toVersion: cli.flags.to,
-  yolo: cli.flags.yolo
-})
-// if having issues with errors being swallowed, uncomment this
-// { debug: true },
-);
+async function main() {
+  renderHeader();
+  const options = {
+    dir: cli.flags.dir,
+    glob: cli.flags.glob,
+    ignore: cli.flags.ignore,
+    dryRun: cli.flags.dryRun,
+    skipCodemods: cli.flags.skipCodemods
+  };
+  if (options.dryRun) {
+    renderWarning(' Upgrade running in dry run mode - no changes will be made');
+    renderNewline();
+  }
+
+  // Step 1: Detect or prompt for SDK
+  let sdk = normalizeSdkName(cli.flags.sdk);
+  if (!sdk) {
+    sdk = detectSdk(options.dir);
+  }
+  if (!sdk) {
+    if (!isInteractive) {
+      renderError('Could not detect Clerk SDK. Please provide --sdk flag in non-interactive mode.');
+      renderText('Supported SDKs: ' + getSupportedSdks().map(s => s.value).join(', '));
+      process.exit(1);
+    }
+    const sdkOptions = getSupportedSdks().map(s => ({
+      label: s.label,
+      value: s.value
+    }));
+    sdk = await promptSelect('Could not detect Clerk SDK. Please select which SDK you are upgrading:', sdkOptions);
+  }
+  if (!sdk) {
+    renderError('No SDK selected. Exiting.');
+    process.exit(1);
+  }
+
+  // Step 2: Get current version and detect package manager
+  const currentVersion = getSdkVersion(sdk, options.dir);
+  const packageManager = detectPackageManager(options.dir);
+
+  // Step 3: Load version config
+  const config = await loadConfig(sdk, currentVersion);
+  if (!config) {
+    renderError(`No upgrade path found for @clerk/${sdk}. Your version may be too old for this upgrade tool.`);
+    process.exit(1);
+  }
+
+  // Step 4: Display configuration
+  renderConfig({
+    sdk,
+    currentVersion,
+    fromVersion: config.sdkVersions?.[sdk]?.from,
+    toVersion: config.sdkVersions?.[sdk]?.to,
+    versionName: config.name,
+    dir: options.dir,
+    packageManager: getPackageManagerDisplayName(packageManager)
+  });
+  if (isInteractive && !(await promptConfirm('Ready to upgrade?'))) {
+    renderError('Upgrade cancelled. Exiting...');
+    process.exit(0);
+  }
+  console.log('');
+
+  // Step 5: Handle upgrade status
+  if (config.alreadyUpgraded) {
+    renderSuccess(`You're already on the latest major version of @clerk/${sdk}`);
+  } else if (config.needsUpgrade) {
+    await performUpgrade(sdk, packageManager, config, options);
+  }
+
+  // Step 6: Run codemods
+  if (config.codemods?.length > 0) {
+    renderText(`Running ${config.codemods.length} codemod(s)...`, 'blue');
+    await runCodemods(config, sdk, options);
+    renderSuccess('All codemods applied');
+    renderNewline();
+  }
+
+  // Step 7: Run scans
+  if (config.changes?.length > 0) {
+    renderText('Scanning for additional breaking changes...', 'blue');
+    const results = await runScans(config, sdk, options);
+    renderScanResults(results, config.docsUrl);
+  }
+
+  // Step 8: Done
+  renderComplete(sdk, config.docsUrl);
+}
+async function performUpgrade(sdk, packageManager, config, options) {
+  const targetPackage = getTargetPackageName(sdk);
+  const oldPackage = getOldPackageName(sdk);
+  const targetVersion = config.sdkVersions?.[sdk]?.to;
+  if (options.dryRun) {
+    renderText(`[dry run] Would upgrade ${targetPackage} to version ${targetVersion}`, 'yellow');
+    if (oldPackage) {
+      renderText(`[dry run] Would remove old package ${oldPackage}`, 'yellow');
+    }
+    renderNewline();
+    return;
+  }
+
+  // Remove old package if this is a rename (clerk-react -> react, clerk-expo -> expo)
+  if (oldPackage) {
+    const removeSpinner = createSpinner(`Removing ${oldPackage}...`);
+    try {
+      await removePackage(packageManager, oldPackage, options.dir);
+      removeSpinner.success(`Removed ${oldPackage}`);
+    } catch {
+      removeSpinner.error(`Failed to remove ${oldPackage}`);
+    }
+  }
+
+  // Upgrade to the new version
+  const spinner = createSpinner(`Upgrading ${targetPackage} to version ${targetVersion}...`);
+  try {
+    await upgradePackage(packageManager, targetPackage, targetVersion, options.dir);
+    spinner.success(`Upgraded ${targetPackage} to version ${targetVersion}`);
+  } catch (error) {
+    spinner.error(`Failed to upgrade ${targetPackage}`);
+    renderError(error.message);
+    process.exit(1);
+  }
+}
+main().catch(error => {
+  renderError(error.message);
+  process.exit(1);
+});

package/dist/codemods/__tests__/__fixtures__/transform-align-experimental-unstable-prefixes.fixtures.js

@@ -0,0 +1,68 @@
+export const fixtures = [{
+  name: 'Renames unstable hooks and handlers to internal',
+  source: `
+const clerk = useClerk();
+clerk.__unstable__updateProps({});
+window.__unstable__onAfterSetActive = () => {};
+const opts = { __unstable_invokeMiddlewareOnAuthStateChange: true };
+const handler = client['__unstable__onAfterResponse'];
+    `,
+  output: `
+const clerk = useClerk();
+clerk.__internal_updateProps({});
+window.__internal_onAfterSetActive = () => {};
+const opts = { __internal_invokeMiddlewareOnAuthStateChange: true };
+const handler = client["__internal_onAfterResponse"];
+`
+}, {
+  name: 'Moves UI theme helpers to experimental path and renames identifiers',
+  source: `
+import { __experimental_createTheme, experimental__simple, Button } from '@clerk/ui';
+
+const theme = __experimental_createTheme();
+const kind = experimental__simple;
+    `,
+  output: `
+import { Button } from '@clerk/ui';
+
+import { createTheme, simple } from "@clerk/ui/themes/experimental";
+
+const theme = createTheme();
+const kind = simple;
+`
+}, {
+  name: 'Moves UI theme helpers required from root to experimental path',
+  source: `
+const { __experimental_createTheme, experimental__simple, Card } = require('@clerk/ui');
+    `,
+  output: `
+const {
+  Card
+} = require('@clerk/ui');
+
+const {
+  createTheme,
+  simple
+} = require("@clerk/ui/themes/experimental");
+`
+}, {
+  name: 'Moves chrome extension client creation to background path',
+  source: `
+import { __unstable__createClerkClient } from '@clerk/chrome-extension';
+
+__unstable__createClerkClient();
+    `,
+  output: `
+import { createClerkClient } from "@clerk/chrome-extension/background";
+
+createClerkClient();
+`
+}, {
+  name: 'Removes deprecated billing props from JSX',
+  source: `
+<OrganizationProfile __unstable_manageBillingUrl="url" experimental__forceOauthFirst />;
+    `,
+  output: `
+<OrganizationProfile />;
+`
+}];

package/dist/codemods/__tests__/__fixtures__/transform-appearance-layout-to-options.fixtures.js

@@ -0,0 +1,9 @@
+export const fixtures = [{
+  name: 'Renames layout inside JSX appearance prop',
+  source: `
+      <SignIn appearance={{ layout: { socialButtonsPlacement: 'top' } }} />
+    `,
+  output: `
+      <SignIn appearance={{ options: { socialButtonsPlacement: 'top' } }} />
+    `
+}];

package/dist/codemods/__tests__/__fixtures__/transform-clerk-react-v6.fixtures.js

@@ -104,4 +104,17 @@ const clerk = require("@clerk/clerk-react")
   output: `
 const clerk = require("@clerk/react")
 `
+}, {
+  name: 'Handles directives with mixed legacy imports without double semicolons',
+  source: `"use client";
+
+import { ClerkProvider, useSignIn, useSignUp } from "@clerk/nextjs";
+
+export const dynamic = "force-dynamic";
+`,
+  output: `"use client";
+import { ClerkProvider } from "@clerk/nextjs";
+import { useSignIn, useSignUp } from "@clerk/nextjs/legacy";
+
+export const dynamic = "force-dynamic";`
 }];

package/dist/codemods/__tests__/__fixtures__/transform-remove-deprecated-appearance-props.fixtures.js

@@ -0,0 +1,63 @@
+export const fixtures = [{
+  name: 'Renames baseTheme to theme in JSX appearance',
+  source: `
+      <SignIn appearance={{ baseTheme: dark }} />
+    `,
+  output: `
+      <SignIn appearance={{ theme: dark }} />
+    `
+}, {
+  name: 'Renames baseTheme and variable keys when appearance object is referenced',
+  source: `
+      const appearance = {
+        baseTheme: [dark, light],
+        variables: {
+          colorText: '#000',
+          colorTextSecondary: '#111',
+          colorInputText: '#222',
+          colorInputBackground: '#333',
+          colorTextOnPrimaryBackground: '#444',
+          spacingUnit: '1rem',
+        },
+      };
+
+      <SignUp appearance={appearance} />
+    `,
+  output: `
+      const appearance = {
+        theme: [dark, light],
+        variables: {
+          colorForeground: '#000',
+          colorMutedForeground: '#111',
+          colorInputForeground: '#222',
+          colorInput: '#333',
+          colorPrimaryForeground: '#444',
+          spacing: '1rem',
+        },
+      };
+
+      <SignUp appearance={appearance} />
+    `
+}, {
+  name: 'Handles string literal keys',
+  source: `
+      const appearance = {
+        'baseTheme': dark,
+        variables: {
+          'colorText': '#000',
+        },
+      };
+
+      <SignIn appearance={appearance} />
+    `,
+  output: `
+      const appearance = {
+        "theme": dark,
+        variables: {
+          "colorForeground": '#000',
+        },
+      };
+
+      <SignIn appearance={appearance} />
+    `
+}];

package/dist/codemods/__tests__/__fixtures__/transform-themes-to-ui-themes.fixtures.js

@@ -0,0 +1,41 @@
+export const fixtures = [{
+  name: 'Renames root import',
+  source: `
+import { dark, light } from '@clerk/themes';
+    `,
+  output: `
+import { dark, light } from "@clerk/ui/themes";
+`
+}, {
+  name: 'Renames subpath import',
+  source: `
+import palette from '@clerk/themes/palette';
+    `,
+  output: `
+import palette from "@clerk/ui/themes/palette";
+`
+}, {
+  name: 'Renames require call',
+  source: `
+const themes = require('@clerk/themes');
+    `,
+  output: `
+const themes = require("@clerk/ui/themes");
+`
+}, {
+  name: 'Renames dynamic import',
+  source: `
+const mod = await import('@clerk/themes/foo');
+    `,
+  output: `
+const mod = await import("@clerk/ui/themes/foo");
+`
+}, {
+  name: 'Renames export source',
+  source: `
+export * from '@clerk/themes';
+    `,
+  output: `
+export * from "@clerk/ui/themes";
+`
+}];

package/dist/codemods/__tests__/transform-align-experimental-unstable-prefixes.test.js

@@ -0,0 +1,15 @@
+import { applyTransform } from 'jscodeshift/dist/testUtils';
+import { describe, expect, it } from 'vitest';
+import transformer from '../transform-align-experimental-unstable-prefixes.cjs';
+import { fixtures } from './__fixtures__/transform-align-experimental-unstable-prefixes.fixtures';
+describe('transform-align-experimental-unstable-prefixes', () => {
+  it.each(fixtures)('$name', ({
+    source,
+    output
+  }) => {
+    const result = applyTransform(transformer, {}, {
+      source
+    });
+    expect(result).toEqual(output.trim());
+  });
+});

package/dist/codemods/__tests__/transform-appearance-layout-to-options.test.js

@@ -0,0 +1,15 @@
+import { applyTransform } from 'jscodeshift/dist/testUtils';
+import { describe, expect, it } from 'vitest';
+import transformer from '../transform-appearance-layout-to-options.cjs';
+import { fixtures } from './__fixtures__/transform-appearance-layout-to-options.fixtures';
+describe('transform-appearance-layout-to-options', () => {
+  it.each(fixtures)('$name', ({
+    source,
+    output
+  }) => {
+    const result = applyTransform(transformer, {}, {
+      source
+    });
+    expect(result).toEqual(output.trim());
+  });
+});

package/dist/codemods/__tests__/transform-remove-deprecated-appearance-props.test.js

@@ -0,0 +1,15 @@
+import { applyTransform } from 'jscodeshift/dist/testUtils';
+import { describe, expect, it } from 'vitest';
+import transformer from '../transform-remove-deprecated-appearance-props.cjs';
+import { fixtures } from './__fixtures__/transform-remove-deprecated-appearance-props.fixtures';
+describe('transform-remove-deprecated-appearance-props', () => {
+  it.each(fixtures)('$name', ({
+    source,
+    output
+  }) => {
+    const result = applyTransform(transformer, {}, {
+      source
+    });
+    expect(result).toEqual(output.trim());
+  });
+});

package/dist/codemods/__tests__/transform-themes-to-ui-themes.test.js

@@ -0,0 +1,15 @@
+import { applyTransform } from 'jscodeshift/dist/testUtils';
+import { describe, expect, it } from 'vitest';
+import transformer from '../transform-themes-to-ui-themes.cjs';
+import { fixtures } from './__fixtures__/transform-themes-to-ui-themes.fixtures';
+describe('transform-themes-to-ui-themes', () => {
+  it.each(fixtures)('$name', ({
+    source,
+    output
+  }) => {
+    const result = applyTransform(transformer, {}, {
+      source
+    });
+    expect(result).toEqual(output.trim());
+  });
+});

package/dist/codemods/index.js

@@ -1,32 +1,86 @@
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
 import { globby } from 'globby';
 import { run } from 'jscodeshift/src/Runner.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const CODEMOD_CONFIG = {
+  'transform-remove-deprecated-props': {
+    renderSummary: renderDeprecatedPropsSummary
+  }
+};
+const GLOBBY_IGNORE = ['**/*.md', 'node_modules/**', '**/node_modules/**', '.git/**', '**/*.json', 'package.json', '**/package.json', 'package-lock.json', '**/package-lock.json', 'yarn.lock', '**/yarn.lock', 'pnpm-lock.yaml', '**/pnpm-lock.yaml', 'yalc.lock', '**/*.(ico|png|webp|svg|gif|jpg|jpeg)+', '**/*.(mp4|mkv|wmv|m4v|mov|avi|flv|webm|flac|mka|m4a|aac|ogg)+', '**/*.(css|scss|sass|less|styl)+'];
 export async function runCodemod(transform = 'transform-async-request', glob, options = {}) {
   if (!transform) {
     throw new Error('No transform provided');
   }
   const resolvedPath = resolve(__dirname, `${transform}.cjs`);
   const paths = await globby(glob, {
-    ignore: ['**/*.md', 'node_modules/**', '**/node_modules/**', '.git/**', '**/*.json', 'package.json', '**/package.json', 'package-lock.json', '**/package-lock.json', 'yarn.lock', '**/yarn.lock', 'pnpm-lock.yaml', '**/pnpm-lock.yaml', 'yalc.lock', '**/*.(ico|png|webp|svg|gif|jpg|jpeg)+',
-    // common image files
-    '**/*.(mp4|mkv|wmv|m4v|mov|avi|flv|webm|flac|mka|m4a|aac|ogg)+',
-    // common video files] }).then(files => {
-    '**/*.(css|scss|sass|less|styl)+' // common style files
-    ]
+    ignore: GLOBBY_IGNORE
   });
-  const clerkUpgradeStats = options.clerkUpgradeStats ?? {};
-  const result = await run(resolvedPath, paths ?? [], {
-    dry: false,
+  if (options.skipCodemods) {
+    return {
+      stats: {
+        total: 0,
+        modified: 0,
+        deleted: 0
+      }
+    };
+  }
+
+  // First pass: dry run to collect stats (jscodeshift only reports stats in dry mode)
+  const dryResult = await run(resolvedPath, paths ?? [], {
     ...options,
-    // expose a mutable stats bag so individual transforms can record structured information
-    clerkUpgradeStats,
-    // we must silence stdout to prevent output from interfering with ink CLI
+    dry: true,
     silent: true
   });
+  let result = {};
+  if (!options.dryRun) {
+    // Second pass: apply the changes
+    result = await run(resolvedPath, paths ?? [], {
+      ...options,
+      dry: false,
+      silent: true
+    });
+  }
+  if (options.dry) {
+    return dryResult;
+  }
+
+  // Merge stats from dry run into final result
   return {
     ...result,
-    clerkUpgradeStats
+    stats: dryResult.stats
   };
+}
+export function getCodemodConfig(transform) {
+  return CODEMOD_CONFIG[transform] || null;
+}
+function renderDeprecatedPropsSummary(stats) {
+  if (!stats) {
+    return;
+  }
+  const userButtonCount = stats.userbuttonAfterSignOutPropsRemoved || 0;
+  const hideSlugCount = stats.hideSlugRemoved || 0;
+  const beforeEmitCount = stats.beforeEmitTransformed || 0;
+  if (!userButtonCount && !hideSlugCount && !beforeEmitCount) {
+    return;
+  }
+  console.log(chalk.yellow.bold('Manual intervention may be required:'));
+  if (userButtonCount > 0) {
+    console.log(chalk.yellow(`• Removed ${userButtonCount} UserButton sign-out redirect prop(s)`));
+    console.log(chalk.gray('  To configure sign-out redirects:'));
+    console.log(chalk.gray('  - Global: Add afterSignOutUrl to <ClerkProvider>'));
+    console.log(chalk.gray('  - Per-button: Use <SignOutButton redirectUrl="...">'));
+    console.log(chalk.gray('  - Programmatic: clerk.signOut({ redirectUrl: "..." })'));
+  }
+  if (hideSlugCount > 0) {
+    console.log(chalk.yellow(`• Removed ${hideSlugCount} hideSlug prop(s)`));
+    console.log(chalk.gray('  Slugs are now managed in the Clerk Dashboard.'));
+  }
+  if (beforeEmitCount > 0) {
+    console.log(chalk.yellow(`• Transformed ${beforeEmitCount} setActive({ beforeEmit }) → setActive({ navigate })`));
+    console.log(chalk.gray('  The callback now receives an object with session property.'));
+  }
+  console.log('');
 }