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

package/dist/__tests__/integration/detect-sdk.test.js

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { detectSdk, getMajorVersion, getSdkVersion, normalizeSdkName } from '../../util/detect-sdk.js';
+import { detectPackageManager } from '../../util/package-manager.js';
+import { getFixturePath } from '../helpers/create-fixture.js';
+describe('detectSdk', () => {
+  it('detects @clerk/nextjs from package.json', () => {
+    const sdk = detectSdk(getFixturePath('nextjs-v6'));
+    expect(sdk).toBe('nextjs');
+  });
+  it('detects @clerk/nextjs v7 from package.json', () => {
+    const sdk = detectSdk(getFixturePath('nextjs-v7'));
+    expect(sdk).toBe('nextjs');
+  });
+  it('detects @clerk/clerk-react (legacy name) from package.json', () => {
+    const sdk = detectSdk(getFixturePath('react-v6'));
+    expect(sdk).toBe('react');
+  });
+  it('detects @clerk/clerk-expo (legacy name) from package.json', () => {
+    const sdk = detectSdk(getFixturePath('expo-old-package'));
+    expect(sdk).toBe('expo');
+  });
+  it('returns null when no Clerk SDK is found', () => {
+    const sdk = detectSdk(getFixturePath('no-clerk'));
+    expect(sdk).toBeNull();
+  });
+});
+describe('getSdkVersion', () => {
+  it('returns major version 6 for nextjs-v6 fixture', () => {
+    const version = getSdkVersion('nextjs', getFixturePath('nextjs-v6'));
+    expect(version).toBe(6);
+  });
+  it('returns major version 7 for nextjs-v7 fixture', () => {
+    const version = getSdkVersion('nextjs', getFixturePath('nextjs-v7'));
+    expect(version).toBe(7);
+  });
+  it('returns major version 5 for clerk-react fixture', () => {
+    const version = getSdkVersion('clerk-react', getFixturePath('react-v6'));
+    expect(version).toBe(5);
+  });
+  it('returns major version 2 for clerk-expo fixture', () => {
+    const version = getSdkVersion('clerk-expo', getFixturePath('expo-old-package'));
+    expect(version).toBe(2);
+  });
+  it('returns null when SDK is not found', () => {
+    const version = getSdkVersion('nextjs', getFixturePath('no-clerk'));
+    expect(version).toBeNull();
+  });
+});
+describe('getMajorVersion', () => {
+  it('parses ^6.0.0 as version 6', () => {
+    expect(getMajorVersion('^6.0.0')).toBe(6);
+  });
+  it('parses ~7.1.2 as version 7', () => {
+    expect(getMajorVersion('~7.1.2')).toBe(7);
+  });
+  it('parses 5.0.0 as version 5', () => {
+    expect(getMajorVersion('5.0.0')).toBe(5);
+  });
+  it('parses 14.2.3 as version 14', () => {
+    expect(getMajorVersion('14.2.3')).toBe(14);
+  });
+  it('returns null for invalid semver', () => {
+    expect(getMajorVersion('invalid')).toBeNull();
+  });
+});
+describe('normalizeSdkName', () => {
+  it('returns null for null input', () => {
+    expect(normalizeSdkName(null)).toBeNull();
+  });
+  it('strips @clerk/ prefix', () => {
+    expect(normalizeSdkName('@clerk/nextjs')).toBe('nextjs');
+  });
+  it('converts clerk-react to react', () => {
+    expect(normalizeSdkName('clerk-react')).toBe('react');
+  });
+  it('converts clerk-expo to expo', () => {
+    expect(normalizeSdkName('clerk-expo')).toBe('expo');
+  });
+  it('returns name unchanged for standard names', () => {
+    expect(normalizeSdkName('nextjs')).toBe('nextjs');
+  });
+});
+describe('detectPackageManager', () => {
+  it('detects pnpm from pnpm-lock.yaml', () => {
+    const pm = detectPackageManager(getFixturePath('nextjs-v6'));
+    expect(pm).toBe('pnpm');
+  });
+  it('detects yarn from yarn.lock', () => {
+    const pm = detectPackageManager(getFixturePath('react-v6'));
+    expect(pm).toBe('yarn');
+  });
+  it('detects npm from package-lock.json', () => {
+    const pm = detectPackageManager(getFixturePath('expo-old-package'));
+    expect(pm).toBe('npm');
+  });
+  it('defaults to npm when no lock file exists', () => {
+    const pm = detectPackageManager(getFixturePath('no-clerk'));
+    expect(pm).toBe('npm');
+  });
+});

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

@@ -0,0 +1,58 @@
+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(results.length).toBeGreaterThan(0);
+  });
+  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(results).toEqual([]);
+  });
+});

package/dist/cli.js

@@ -1,68 +1,196 @@
 #!/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)
+      --skip-upgrade     Skip the upgrade step
+      --release          Name of the release you're upgrading to (e.g. core-3)
+      --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'
+    skipUpgrade: {
+      type: 'boolean',
+      default: false
     },
-    noWarnings: {
-      type: 'boolean'
+    release: {
+      type: 'string'
+    },
+    dryRun: {
+      type: 'boolean',
+      default: false
     },
-    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,
+    skipUpgrade: cli.flags.skipUpgrade,
+    release: cli.flags.release,
+    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, options.release);
+  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?', true))) {
+    renderError('Upgrade cancelled. Exiting...');
+    process.exit(0);
+  }
+  console.log('');
+
+  // Step 5: Handle upgrade status
+  if (options.skipUpgrade) {
+    renderText('Skipping package upgrade (--skip-upgrade flag)', 'yellow');
+    renderNewline();
+  } else 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,92 @@
+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 />;
+`
+}, {
+  name: 'Does not rename class constructors',
+  source: `
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500
+  ) {
+    super(message);
+  }
+}
+    `,
+  output: `
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500
+  ) {
+    super(message);
+  }
+}
+`
+}];

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
+    }) || source.trim();
+    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());
+  });
+});