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

package/README.md

@@ -27,25 +27,55 @@
 
 ## Getting Started
 
-A tool that helps with upgrading major versions of Clerk's SDKs.
+A CLI that detects your installed Clerk SDK, upgrades packages to the next major release, runs codemods, and scans your codebase for breaking changes.
 
 ### Prerequisites
 
-- Node.js `>=18.17.0` or later
+- Node.js `>=20.9.0`
+- pnpm, npm, or yarn installed in the target project
 
 ## Usage
 
-Navigate to the application you want to upgrade and run the following in your terminal:
+Run the CLI from the root of the project you want to upgrade:
 
 ```sh
+# with pnpm
+pnpm dlx @clerk/upgrade
+
+# with npm
 npx @clerk/upgrade
+
+# if installed locally
+pnpm clerk-upgrade
 ```
 
-Fill out the questionnaire and the CLI will show you the required changes.
+Fill out the prompts and the CLI will:
+
+- Detect your Clerk SDK and version (or prompt for `--sdk`)
+- Upgrade packages (including renames such as `@clerk/clerk-react` → `@clerk/react`)
+- Run codemods for the selected release
+- Scan your files for breaking changes and print a report
+
+### CLI options
+
+- `--sdk` — SDK to upgrade (e.g., `nextjs`, `react`, `expo`); required in non-interactive runs if detection fails
+- `--dir` — directory to scan (default: current working directory)
+- `--glob` — glob of files for codemods (default: `**/*.(js|jsx|ts|tsx|mjs|cjs)`)
+- `--ignore` — extra globs to ignore during scans (repeatable)
+- `--release` — target release (e.g., `core-3`); otherwise auto-selected from installed versions
+- `--skip-upgrade` — skip installing/updating packages
+- `--skip-codemods` — skip codemod execution
+- `--dry-run` — show what would change without writing or installing
+
+### Releases
+
+- `core-3`: upgrades Next.js 6 → 7, React 5 → 7, Expo 2 → 3, React Router 2 → 3, TanStack React Start 0 → 1, Astro 2 → 3, Nuxt 2 → 3, Vue 2 → 3; includes package renames for React/Expo
+
+The CLI selects the appropriate release automatically based on the installed major version, or you can pin a release with `--release` (currently `core-3`).
 
 ### Caveats
 
-This tool uses regular expressions to scan for patterns that match breaking changes. This makes it run substantially faster and makes it more accessible for us at Clerk to author matchers for each breaking change, however it means that _we cannot gurarantee 100% accuracy of the results_. As such, it's important to treat this as a tool that can help you to complete your major version upgrades, rather than an automatic fix to all issues.
+Scans rely on regular expressions, so some patterns (unusual imports, bound methods, indirect calls) can be missed. Codemods cover common upgrades, but you should still review the report, run your test suite, and verify the app before deploying.
 
 The main thing that this tool will miss is cases where _unusual import patterns_ are used in your codebase. As an example, if Clerk made a breaking change to the `getAuth` function exported from `@clerk/nextjs`, `@clerk/upgrade` would likely look for something like `import { getAuth } from "@clerk/nextjs"` in order to detect whether you need to make some changes. If you were using your imports like `import * as ClerkNext from "@clerk/nextjs"`, you could use `getAuth` without it detecting it with its matcher.
 

package/dist/__tests__/fixtures/nextjs-v6/src/app.tsx

@@ -1,8 +1,8 @@
-import { ClerkProvider, useAuth, useUser } from '@clerk/nextjs';
-import { dark } from '@clerk/nextjs/themes';
+import { ClerkProvider, useAuth } from '@clerk/nextjs';
+import { useUser } from '@clerk/clerk-react';
 
 export default function App({ children }) {
-  return <ClerkProvider appearance={{ baseTheme: dark }}>{children}</ClerkProvider>;
+  return <ClerkProvider>{children}</ClerkProvider>;
 }
 
 export function UserProfile() {

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

@@ -74,6 +74,8 @@ describe('CLI Integration', () => {
       expect(result.stdout).toContain('--sdk');
       expect(result.stdout).toContain('--dir');
       expect(result.stdout).toContain('--dry-run');
+      expect(result.stdout).toContain('--skip-upgrade');
+      expect(result.stdout).toContain('--release');
       expect(result.exitCode).toBe(0);
     });
   });
@@ -227,4 +229,47 @@ describe('CLI Integration', () => {
       expect(result.stdout).toContain('codemod');
     });
   });
+  describe('--skip-upgrade flag', () => {
+    let fixture;
+    beforeEach(() => {
+      fixture = createTempFixture('nextjs-v6');
+    });
+    afterEach(() => {
+      fixture?.cleanup();
+    });
+    it('skips the package upgrade step', async () => {
+      const result = await runCli(['--dir', fixture.path, '--skip-upgrade', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('Skipping package upgrade');
+      expect(result.stdout).toContain('--skip-upgrade');
+    });
+    it('does not modify package.json when skipping upgrade', 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);
+    });
+  });
+  describe('--release flag', () => {
+    it('loads specific release configuration', async () => {
+      const dir = getFixturePath('nextjs-v7');
+      const result = await runCli(['--dir', dir, '--release', 'core-3', '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('core-3');
+    });
+    it('errors when release does not exist', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--release', 'nonexistent-release', '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      const output = result.stdout + result.stderr;
+      expect(output).toContain('No upgrade path found');
+      expect(result.exitCode).toBe(1);
+    });
+  });
 });

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

@@ -45,6 +45,27 @@ describe('loadConfig', () => {
     expect(config.docsUrl).toBeDefined();
     expect(config.docsUrl).toContain('clerk.com');
   });
+  describe('release parameter', () => {
+    it('loads specific release when provided', async () => {
+      const config = await loadConfig('nextjs', 7, 'core-3');
+      expect(config).not.toBeNull();
+      expect(config.id).toBe('core-3');
+    });
+    it('returns null for non-existent release', async () => {
+      const config = await loadConfig('nextjs', 6, 'nonexistent-release');
+      expect(config).toBeNull();
+    });
+    it('ignores version status when release is specified', async () => {
+      const config = await loadConfig('nextjs', 7, 'core-3');
+      expect(config).not.toBeNull();
+      expect(config.alreadyUpgraded).toBe(true);
+    });
+    it('loads changes for specific release', async () => {
+      const config = await loadConfig('nextjs', 6, 'core-3');
+      expect(config.changes).toBeDefined();
+      expect(Array.isArray(config.changes)).toBe(true);
+    });
+  });
 });
 describe('getTargetPackageName', () => {
   it('returns @clerk/react for react sdk', () => {

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

@@ -34,7 +34,7 @@ describe('runScans', () => {
       ignore: []
     };
     const results = await runScans(config, 'nextjs', options);
-    expect(Array.isArray(results)).toBe(true);
+    expect(results.length).toBeGreaterThan(0);
   });
   it('returns empty array when no matchers match', async () => {
     const config = await loadConfig('nextjs', 6);
@@ -53,27 +53,6 @@ describe('runScans', () => {
       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);
-    }
+    expect(results).toEqual([]);
   });
 });

package/dist/cli.js

@@ -15,6 +15,8 @@ const cli = meow(`
       --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
@@ -43,6 +45,13 @@ const cli = meow(`
       type: 'string',
       isMultiple: true
     },
+    skipUpgrade: {
+      type: 'boolean',
+      default: false
+    },
+    release: {
+      type: 'string'
+    },
     dryRun: {
       type: 'boolean',
       default: false
@@ -59,6 +68,8 @@ async function main() {
     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
   };
@@ -94,7 +105,7 @@ async function main() {
   const packageManager = detectPackageManager(options.dir);
 
   // Step 3: Load version config
-  const config = await loadConfig(sdk, currentVersion);
+  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);
@@ -110,14 +121,17 @@ async function main() {
     dir: options.dir,
     packageManager: getPackageManagerDisplayName(packageManager)
   });
-  if (isInteractive && !(await promptConfirm('Ready to upgrade?'))) {
+  if (isInteractive && !(await promptConfirm('Ready to upgrade?', true))) {
     renderError('Upgrade cancelled. Exiting...');
     process.exit(0);
   }
   console.log('');
 
   // Step 5: Handle upgrade status
-  if (config.alreadyUpgraded) {
+  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);

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

@@ -65,4 +65,28 @@ createClerkClient();
   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__/transform-align-experimental-unstable-prefixes.test.js

@@ -9,7 +9,7 @@ describe('transform-align-experimental-unstable-prefixes', () => {
   }) => {
     const result = applyTransform(transformer, {}, {
       source
-    });
+    }) || source.trim();
     expect(result).toEqual(output.trim());
   });
 });

package/dist/codemods/index.js

@@ -9,7 +9,7 @@ const CODEMOD_CONFIG = {
     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)+'];
+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');

package/dist/codemods/transform-align-experimental-unstable-prefixes.cjs

@@ -1,18 +1,18 @@
-const SPECIFIC_RENAMES = {
-  experimental_createTheme: 'createTheme',
+const SPECIFIC_RENAMES = Object.freeze({
   __experimental_createTheme: 'createTheme',
-  experimental__simple: 'simple',
   __experimental_simple: 'simple',
   __unstable__createClerkClient: 'createClerkClient',
-  __unstable_invokeMiddlewareOnAuthStateChange: '__internal_invokeMiddlewareOnAuthStateChange',
   __unstable__environment: '__internal_environment',
-  __unstable__updateProps: '__internal_updateProps',
-  __unstable__setEnvironment: '__internal_setEnvironment',
-  __unstable__onBeforeRequest: '__internal_onBeforeRequest',
   __unstable__onAfterResponse: '__internal_onAfterResponse',
+  __unstable__onAfterSetActive: '__internal_onAfterSetActive',
+  __unstable__onBeforeRequest: '__internal_onBeforeRequest',
   __unstable__onBeforeSetActive: '__internal_onBeforeSetActive',
-  __unstable__onAfterSetActive: '__internal_onAfterSetActive'
-};
+  __unstable__setEnvironment: '__internal_setEnvironment',
+  __unstable__updateProps: '__internal_updateProps',
+  __unstable_invokeMiddlewareOnAuthStateChange: '__internal_invokeMiddlewareOnAuthStateChange',
+  experimental__simple: 'simple',
+  experimental_createTheme: 'createTheme'
+});
 const REMOVED_PROPS = new Set(['__unstable_manageBillingUrl', '__unstable_manageBillingLabel', '__unstable_manageBillingMembersLimit', 'experimental__forceOauthFirst']);
 const UI_THEME_NAMES = new Set(['createTheme', 'simple', 'experimental_createTheme', '__experimental_createTheme', 'experimental__simple', '__experimental_simple']);
 const UI_THEME_SOURCE = '@clerk/ui/themes/experimental';
@@ -20,6 +20,18 @@ const UI_LEGACY_SOURCES = new Set(['@clerk/ui', '@clerk/ui/themes', UI_THEME_SOU
 const CHROME_CLIENT_NAMES = new Set(['__unstable__createClerkClient', 'createClerkClient']);
 const CHROME_BACKGROUND_SOURCE = '@clerk/chrome-extension/background';
 const CHROME_LEGACY_SOURCE = '@clerk/chrome-extension';
+
+/**
+ * Transforms experimental and unstable prefixed identifiers to their stable or internal equivalents.
+ * Also moves theme-related imports to @clerk/ui/themes/experimental and Chrome extension imports
+ * to @clerk/chrome-extension/background. Removes deprecated billing-related props.
+ *
+ * @param {Object} file - The file object containing the source code
+ * @param {string} file.source - The source code to transform
+ * @param {Object} api - The jscodeshift API
+ * @param {Function} api.jscodeshift - The jscodeshift function
+ * @returns {string|undefined} The transformed source code, or undefined if no changes were made
+ */
 module.exports = function transformAlignExperimentalUnstablePrefixes({
   source
 }, {
@@ -28,10 +40,10 @@ module.exports = function transformAlignExperimentalUnstablePrefixes({
   const root = j(source);
   let dirty = false;
   const maybeRename = name => {
-    if (!name || REMOVED_PROPS.has(name)) {
+    if (!name || REMOVED_PROPS.has(name) || !Object.hasOwn(SPECIFIC_RENAMES, name)) {
       return null;
     }
-    return SPECIFIC_RENAMES[name] ?? null;
+    return SPECIFIC_RENAMES[name];
   };
   const renameIdentifier = node => {
     const newName = maybeRename(node.name);
@@ -164,7 +176,7 @@ module.exports = function transformAlignExperimentalUnstablePrefixes({
       }
     });
   });
-  root.find(j.Identifier).forEach(path => {
+  root.find(j.Identifier).filter(path => maybeRename(path.node.name)).forEach(path => {
     renameIdentifier(path.node);
   });
   root.find(j.JSXOpeningElement).forEach(path => {

package/dist/config.js

@@ -4,10 +4,33 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import matter from 'gray-matter';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const VERSIONS_DIR = path.join(__dirname, 'versions');
-export async function loadConfig(sdk, currentVersion) {
+export async function loadConfig(sdk, currentVersion, release) {
   const versionDirs = fs.readdirSync(VERSIONS_DIR, {
     withFileTypes: true
   }).filter(d => d.isDirectory()).map(d => d.name);
+
+  // If a specific release is requested, load it directly
+  if (release) {
+    if (!versionDirs.includes(release)) {
+      return null;
+    }
+    const configPath = path.join(VERSIONS_DIR, release, 'index.js');
+    if (!fs.existsSync(configPath)) {
+      return null;
+    }
+    const moduleUrl = pathToFileURL(configPath).href;
+    const mod = await import(moduleUrl);
+    const config = mod.default ?? mod;
+    const changes = loadChanges(release, sdk);
+    const versionStatus = getVersionStatus(config, sdk, currentVersion);
+    return {
+      ...config,
+      changes,
+      versionStatus,
+      needsUpgrade: versionStatus === 'needs-upgrade',
+      alreadyUpgraded: versionStatus === 'already-upgraded'
+    };
+  }
   let applicableConfig = null;
   for (const versionDir of versionDirs) {
     const configPath = path.join(VERSIONS_DIR, versionDir, 'index.js');

package/dist/render.js

@@ -43,15 +43,21 @@ export function renderConfig({
   }
   console.log('');
 }
-export async function promptConfirm(message) {
+export async function promptConfirm(message, defaultYes = false) {
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout
   });
   return new Promise(resolve => {
-    rl.question(`${message} (y/n): `, answer => {
+    const prompt = defaultYes ? `${message} (Y/n): ` : `${message} (y/N): `;
+    rl.question(prompt, answer => {
       rl.close();
-      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+      const normalized = answer.trim().toLowerCase();
+      if (!normalized) {
+        resolve(defaultYes);
+        return;
+      }
+      resolve(normalized === 'y' || normalized === 'yes');
     });
   });
 }

package/dist/runner.js

@@ -5,7 +5,7 @@ import { convertPathToPattern, globby } from 'globby';
 import indexToPosition from 'index-to-position';
 import { getCodemodConfig, runCodemod } from './codemods/index.js';
 import { createSpinner, renderCodemodResults } from './render.js';
-const GLOBBY_IGNORE = ['node_modules/**', '**/node_modules/**', '.git/**', 'dist/**', '**/dist/**', 'build/**', '**/build/**', '.next/**', '**/.next/**', 'package.json', '**/package.json', 'package-lock.json', '**/package-lock.json', 'yarn.lock', '**/yarn.lock', 'pnpm-lock.yaml', '**/pnpm-lock.yaml', '**/*.(png|webp|svg|gif|jpg|jpeg)+', '**/*.(mp4|mkv|wmv|m4v|mov|avi|flv|webm|flac|mka|m4a|aac|ogg)+'];
+const GLOBBY_IGNORE = ['node_modules/**', '**/node_modules/**', '.git/**', 'dist/**', '**/dist/**', 'build/**', '**/build/**', '.next/**', '**/.next/**', 'package.json', '**/package.json', 'package-lock.json', '**/package-lock.json', 'yarn.lock', '**/yarn.lock', 'pnpm-lock.yaml', '**/pnpm-lock.yaml', '**/*.{png,webp,svg,gif,jpg,jpeg}', '**/*.{mp4,mkv,wmv,m4v,mov,avi,flv,webm,flac,mka,m4a,aac,ogg}'];
 export async function runCodemods(config, sdk, options) {
   const codemods = config.codemods || [];
   if (codemods.length === 0) {

package/dist/versions/core-3/changes/clerk-react-package-rename.md

@@ -1,6 +1,5 @@
 ---
 title: '`@clerk/clerk-react` renamed to `@clerk/react`'
-packages: ['react']
 matcher: '@clerk/clerk-react'
 category: 'breaking'
 docsAnchor: 'clerk-react-rename'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerk/upgrade",
-  "version": "2.0.0-snapshot.v20251208202852",
+  "version": "2.0.0-snapshot.v20251211120550",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/clerk/javascript.git",