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

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__/fixtures/nextjs-v6-scan-issues/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "test-nextjs-v6-scan-issues",
+  "version": "1.0.0",
+  "dependencies": {
+    "@clerk/nextjs": "^6.0.0",
+    "next": "^14.0.0",
+    "react": "^18.0.0"
+  }
+}

package/dist/__tests__/fixtures/nextjs-v6-scan-issues/pnpm-lock.yaml

@@ -0,0 +1,2 @@
+lockfileVersion: '6.0'
+

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

@@ -0,0 +1,30 @@
+import { ClerkProvider, SignIn, useAuth } from '@clerk/nextjs';
+
+export default function App({ children }) {
+  return (
+    <ClerkProvider
+      appearance={{
+        layout: {
+          socialButtonsPlacement: 'bottom',
+        },
+      }}
+    >
+      {children}
+    </ClerkProvider>
+  );
+}
+
+export function SignInPage() {
+  return (
+    <SignIn
+      afterSignInUrl='/dashboard'
+      afterSignUpUrl='/onboarding'
+    />
+  );
+}
+
+export function SamlCallback() {
+  const { isSignedIn } = useAuth();
+  // Handle saml callback
+  return <div>SAML SSO Callback</div>;
+}

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
@@ -28,13 +30,14 @@ const cli = meow(`
 `, {
   importMeta: import.meta,
   flags: {
-    sdk: {
-      type: 'string'
-    },
     dir: {
       type: 'string',
       default: process.cwd()
     },
+    dryRun: {
+      type: 'boolean',
+      default: false
+    },
     glob: {
       type: 'string',
       default: '**/*.(js|jsx|ts|tsx|mjs|cjs)'
@@ -43,11 +46,17 @@ const cli = meow(`
       type: 'string',
       isMultiple: true
     },
-    dryRun: {
+    release: {
+      type: 'string'
+    },
+    sdk: {
+      type: 'string'
+    },
+    skipCodemods: {
       type: 'boolean',
       default: false
     },
-    skipCodemods: {
+    skipUpgrade: {
       type: 'boolean',
       default: false
     }
@@ -57,10 +66,12 @@ async function main() {
   renderHeader();
   const options = {
     dir: cli.flags.dir,
+    dryRun: cli.flags.dryRun,
     glob: cli.flags.glob,
     ignore: cli.flags.ignore,
-    dryRun: cli.flags.dryRun,
-    skipCodemods: cli.flags.skipCodemods
+    release: cli.flags.release,
+    skipCodemods: cli.flags.skipCodemods,
+    skipUpgrade: cli.flags.skipUpgrade
   };
   if (options.dryRun) {
     renderWarning(' Upgrade running in dry run mode - no changes will be made');
@@ -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

@@ -1,21 +1,21 @@
 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';
+import { glob } from 'tinyglobby';
 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 = {}) {
+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', patterns, options = {}) {
   if (!transform) {
     throw new Error('No transform provided');
   }
   const resolvedPath = resolve(__dirname, `${transform}.cjs`);
-  const paths = await globby(glob, {
+  const paths = await glob(patterns, {
     ignore: GLOBBY_IGNORE
   });
   if (options.skipCodemods) {

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';
@@ -28,10 +28,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 +164,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

@@ -1,8 +1,38 @@
 import * as readline from 'node:readline';
 import chalk from 'chalk';
+const gradientColors = ['#5ee7df', '#b490ca'];
+const hexToRgb = hex => {
+  const value = hex.replace('#', '');
+  const chunk = value.length === 3 ? value.split('').map(char => char + char) : value.match(/.{2}/g);
+  return chunk.map(part => parseInt(part, 16));
+};
+const interpolate = (start, end, t) => Math.round(start + (end - start) * t);
+const applyGradient = text => {
+  if (!text) {
+    return '';
+  }
+  const rgb = gradientColors.map(hexToRgb);
+  const maxIndex = text.length - 1 || 1;
+  const segmentCount = rgb.length - 1;
+  return text.split('').map((char, index) => {
+    const progress = index / maxIndex;
+    const segment = Math.min(Math.floor(progress * segmentCount), segmentCount - 1);
+    const localT = segmentCount === 0 ? 0 : progress * segmentCount - segment;
+    const [r1, g1, b1] = rgb[segment];
+    const [r2, g2, b2] = rgb[segment + 1] || rgb[segment];
+    const r = interpolate(r1, r2, localT);
+    const g = interpolate(g1, g2, localT);
+    const b = interpolate(b1, b2, localT);
+    return chalk.rgb(r, g, b)(char);
+  }).join('');
+};
 export function renderHeader() {
   console.log('');
-  console.log(chalk.magenta.bold('>> Clerk Upgrade CLI <<'));
+  const heading = [' █▀▀ █   █▀▀ █▀█ █▄▀   █ █ █▀█ █▀▀ █▀█ ▄▀█ █▀▄ █▀▀', ' █▄▄ █▄▄ ██▄ █▀▄ █ █   █▄█ █▀▀ █▄█ █▀▄ █▀█ █▄▀ ██▄'];
+  heading.forEach(line => console.log(applyGradient(line)));
+  console.log('');
+  console.log("Hello friend! We're excited to help you upgrade Clerk modules. Before we get started, a couple");
+  console.log('questions...');
   console.log('');
 }
 export function renderText(message, color) {
@@ -43,15 +73,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

@@ -1,21 +1,21 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import chalk from 'chalk';
-import { convertPathToPattern, globby } from 'globby';
 import indexToPosition from 'index-to-position';
+import { glob } from 'tinyglobby';
 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) {
     return;
   }
-  const glob = typeof options.glob === 'string' ? options.glob.split(/[ ,]/).filter(Boolean) : options.glob;
+  const patterns = typeof options.glob === 'string' ? options.glob.split(/[ ,]/).filter(Boolean) : options.glob;
   for (const transform of codemods) {
     const spinner = createSpinner(`Running codemod: ${transform}`);
     try {
-      const result = await runCodemod(transform, glob, options);
+      const result = await runCodemod(transform, patterns, options);
       spinner.success(`Codemod applied: ${chalk.dim(transform)}`);
       renderCodemodResults(transform, result);
       const codemodConfig = getCodemodConfig(transform);
@@ -35,8 +35,10 @@ export async function runScans(config, sdk, options) {
   }
   const spinner = createSpinner('Scanning files for breaking changes...');
   try {
-    const pattern = convertPathToPattern(path.resolve(options.dir));
-    const files = await globby(pattern, {
+    const cwd = path.resolve(options.dir);
+    const files = await glob('**/*', {
+      cwd,
+      absolute: true,
       ignore: [...GLOBBY_IGNORE, ...(options.ignore || [])]
     });
     const results = {};

package/dist/versions/core-3/changes/after-switch-organization-url-removed.md

@@ -0,0 +1,14 @@
+---
+title: '`afterSwitchOrganizationUrl` removed from `OrganizationSwitcher`'
+matcher: 'afterSwitchOrganizationUrl'
+category: 'deprecation-removal'
+---
+
+The `afterSwitchOrganizationUrl` prop has been removed from `OrganizationSwitcher`. Use `afterSelectOrganizationUrl` instead:
+
+```diff
+<OrganizationSwitcher
+- afterSwitchOrganizationUrl="/org-dashboard"
++ afterSelectOrganizationUrl="/org-dashboard"
+/>
+```

package/dist/versions/core-3/changes/appearance-layout-to-options.md

@@ -0,0 +1,20 @@
+---
+title: '`appearance.layout` renamed to `appearance.options`'
+matcher: 'appearance[\\s\\S]*?\\.layout'
+matcherFlags: 'm'
+category: 'breaking'
+---
+
+The `appearance.layout` property has been renamed to `appearance.options`. Update all instances in your codebase:
+
+```diff
+<ClerkProvider
+  appearance={{
+-   layout: {
++   options: {
+      socialButtonsPlacement: 'bottom',
+      socialButtonsVariant: 'iconButton',
+    }
+  }}
+>
+```

package/dist/versions/core-3/changes/billing-props-removed.md

@@ -0,0 +1,14 @@
+---
+title: 'Unstable billing props removed'
+matcher:
+  - '__unstable_manageBillingUrl'
+  - '__unstable_manageBillingLabel'
+  - '__unstable_manageBillingMembersLimit'
+category: 'deprecation-removal'
+---
+
+The following unstable properties have been removed. If you were relying on these, please reach out to support.
+
+- `__unstable_manageBillingUrl`
+- `__unstable_manageBillingLabel`
+- `__unstable_manageBillingMembersLimit`

package/dist/versions/core-3/changes/checkout-api-changed.md

@@ -0,0 +1,35 @@
+---
+title: '`useCheckout` and `Clerk.checkout()` return value changed'
+matcher:
+  - 'useCheckout'
+  - 'Clerk\\.checkout'
+  - '\.checkout\('
+category: 'breaking'
+---
+
+The return values of `useCheckout` hook and `Clerk.checkout()` have been updated.
+
+### React Hook
+
+```diff
+- const { id, plan, status, start, confirm, paymentSource } = useCheckout({ planId: "xxx", planPeriod: "annual" });
++ const { checkout, errors, fetchStatus } = useCheckout({ planId: "xxx", planPeriod: "annual" });
++ // Access properties via checkout object
++ checkout.plan
++ checkout.status
++ checkout.start()
++ checkout.confirm()
+```
+
+### Vanilla JS
+
+```diff
+- const { getState, subscribe, confirm, start, clear, finalize } = Clerk.checkout({ planId: "xxx", planPeriod: "annual" });
+- getState().isStarting
+- getState().checkout
++ const { checkout, errors, fetchStatus } = Clerk.checkout({ planId: "xxx", planPeriod: "annual" });
++ checkout.plan
++ checkout.status
++ checkout.start()
++ checkout.confirm()
+```

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/dist/versions/core-3/changes/clerk-types-deprecation.md

@@ -0,0 +1,17 @@
+---
+title: '`@clerk/types` deprecated in favor of `@clerk/shared/types`'
+matcher: "from\\s+['\"]@clerk/types['\"]"
+category: 'deprecation'
+warning: true
+---
+
+The `@clerk/types` package is deprecated. All type definitions have been consolidated into `@clerk/shared/types`.
+
+Update your imports:
+
+```diff
+- import type { ClerkResource, UserResource } from '@clerk/types';
++ import type { ClerkResource, UserResource } from '@clerk/shared/types';
+```
+
+The `@clerk/types` package will continue to re-export types from `@clerk/shared/types` for backward compatibility, but new types will only be added to `@clerk/shared/types`.

package/dist/versions/core-3/changes/client-active-sessions-removed.md

@@ -0,0 +1,12 @@
+---
+title: '`Client.activeSessions` removed'
+matcher: '\\.activeSessions'
+category: 'deprecation-removal'
+---
+
+The `activeSessions` property has been removed from the `Client` object. Use `sessions` instead:
+
+```diff
+- const sessions = client.activeSessions;
++ const sessions = client.sessions;
+```

package/dist/versions/core-3/changes/color-ring-backdrop-opacity.md

@@ -0,0 +1,21 @@
+---
+title: '`colorRing` and `colorModalBackdrop` now render at full opacity'
+matcher:
+  - 'colorRing'
+  - 'colorModalBackdrop'
+category: 'breaking'
+warning: true
+---
+
+The `colorRing` and `colorModalBackdrop` CSS variables now render at full opacity when modified via the appearance prop or CSS variables. Previously, provided colors were rendered at 15% opacity.
+
+If you were relying on the previous behavior, you may need to adjust your color values to include the desired opacity:
+
+```diff
+appearance={{
+  variables: {
+-   colorRing: '#6366f1',
++   colorRing: 'rgba(99, 102, 241, 0.15)',
+  }
+}}
+```

package/dist/versions/core-3/changes/deprecated-redirect-props-removed.md

@@ -0,0 +1,29 @@
+---
+title: 'Legacy redirect props removed'
+matcher:
+  - 'afterSignInUrl'
+  - 'afterSignUpUrl'
+  - 'afterSignOutUrl'
+  - 'redirectUrl'
+category: 'deprecation-removal'
+---
+
+The legacy redirect props `afterSignInUrl`, `afterSignUpUrl`, and `redirectUrl` have been removed from components. Use the newer redirect options:
+
+```diff
+<SignIn
+- afterSignInUrl="/dashboard"
+- afterSignUpUrl="/onboarding"
++ fallbackRedirectUrl="/dashboard"
++ signUpFallbackRedirectUrl="/onboarding"
+/>
+```
+
+For forced redirects that ignore the `redirect_url` query parameter:
+
+```diff
+<SignIn
++ forceRedirectUrl="/dashboard"
++ signUpForceRedirectUrl="/onboarding"
+/>
+```

package/dist/versions/core-3/changes/experimental-prefix-aligned.md

@@ -0,0 +1,17 @@
+---
+title: 'Experimental method prefix standardized to `__experimental_`'
+matcher:
+  - 'experimental__'
+  - 'experimental_'
+category: 'breaking'
+---
+
+All experimental methods now use the `__experimental_` prefix consistently. Update any references:
+
+```diff
+- experimental__someMethod
++ __experimental_someMethod
+
+- experimental_someMethod
++ __experimental_someMethod
+```

package/dist/versions/core-3/changes/expo-min-version.md

@@ -0,0 +1,24 @@
+---
+title: 'Minimum Expo version increased to 53'
+packages: ['expo']
+matcher: "expo\":\\s*\"(?:^|~|>|=|\\s)*(?:50|51|52)\\..*?"
+matcherFlags: 'm'
+category: 'version'
+---
+
+Support for Expo 50, 51, and 52 has been dropped. Update your project to Expo 53 or later:
+
+```diff
+{
+  "dependencies": {
+-   "expo": "~52.0.0",
++   "expo": "~53.0.0",
+  }
+}
+```
+
+Run the Expo upgrade command:
+
+```bash
+npx expo install expo@latest
+```

package/dist/versions/core-3/changes/hide-slug-removed.md

@@ -0,0 +1,15 @@
+---
+title: '`hideSlug` prop removed'
+matcher: 'hideSlug'
+category: 'deprecation-removal'
+---
+
+The `hideSlug` prop has been removed. Organization slugs are now managed through the Clerk Dashboard under Organization Settings.
+
+```diff
+<OrganizationProfile
+- hideSlug={true}
+/>
+```
+
+To hide organization slugs, update your settings in the Clerk Dashboard → Organization Settings → Slug.

package/dist/versions/core-3/changes/min-node-version.md

@@ -0,0 +1,17 @@
+---
+title: 'Upgrade Node.js to v20.9.0 or higher'
+category: 'version'
+matcher: "engines\":\\s*{[\\s\\S]*?\"node\":\\s*\"(?:^|~|>|=|\\s)*(?:14|16|18)\\..*?"
+matcherFlags: 'm'
+---
+
+All Clerk packages now require Node.js 20.9.0 or later. Update your Node.js version and ensure your `package.json` engines field reflects this requirement.
+
+```diff
+{
+  "engines": {
+-   "node": ">=18.0.0"
++   "node": ">=20.9.0"
+  }
+}
+```

package/dist/versions/core-3/changes/nextjs-encryption-key-required.md

@@ -0,0 +1,17 @@
+---
+title: 'Encryption key required when passing `secretKey` at runtime'
+packages: ['nextjs']
+matcher: 'clerkMiddleware\([\\s\\S]*?secretKey'
+matcherFlags: 'm'
+category: 'breaking'
+---
+
+When passing `secretKey` as a runtime option to `clerkMiddleware()`, you must now also provide a `CLERK_ENCRYPTION_KEY` environment variable.
+
+Add the encryption key to your environment:
+
+```env
+CLERK_ENCRYPTION_KEY=your-encryption-key
+```
+
+More information: https://clerk.com/docs/reference/nextjs/clerk-middleware#dynamic-keys

package/dist/versions/core-3/changes/nuxt-getauth-removed.md

@@ -0,0 +1,21 @@
+---
+title: '`getAuth()` helper removed'
+packages: ['nuxt']
+matcher: 'getAuth\\('
+category: 'deprecation-removal'
+---
+
+The deprecated `getAuth()` helper has been removed. Use `event.context.auth()` in your server routes instead:
+
+```diff
+- import { getAuth } from '@clerk/nuxt/server';
+
+export default defineEventHandler((event) => {
+- const { userId } = getAuth(event);
++ const { userId } = event.context.auth();
+
+  return {
+    userId,
+  };
+});
+```

package/dist/versions/core-3/changes/nuxt-routing-strategy-default-path.md

@@ -0,0 +1,28 @@
+---
+title: 'Routing strategy now defaults to `path`'
+packages: ['nuxt']
+matcher:
+  - '<SignIn'
+  - '<SignUp'
+  - '<UserProfile'
+  - '<OrganizationProfile'
+  - '<CreateOrganization'
+  - '<OrganizationList'
+category: 'behavior-change'
+warning: true
+---
+
+The following components now default to `path` routing strategy instead of `hash`:
+
+- `<SignIn />`
+- `<SignUp />`
+- `<UserProfile />`
+- `<OrganizationProfile />`
+- `<CreateOrganization />`
+- `<OrganizationList />`
+
+If you were relying on the previous `hash` routing behavior, explicitly set the routing prop:
+
+```vue
+<SignIn routing="hash" />
+```

package/dist/versions/core-3/changes/saml-account-renamed.md

@@ -0,0 +1,15 @@
+---
+title: '`samlAccount` renamed to `enterpriseAccount`'
+matcher: 'samlAccount'
+category: 'deprecation-removal'
+---
+
+The `samlAccount` property has been renamed to `enterpriseAccount`. Update your code:
+
+```diff
+- user.samlAccounts
++ user.enterpriseAccounts
+
+- verification.samlAccount
++ verification.enterpriseAccount
+```

package/dist/versions/core-3/changes/saml-to-enterprise-sso.md

@@ -0,0 +1,12 @@
+---
+title: '`saml` strategy renamed to `enterprise_sso`'
+matcher: 'saml'
+category: 'deprecation-removal'
+---
+
+The `saml` authentication strategy has been renamed to `enterprise_sso`. Update any references in your code:
+
+```diff
+- strategy: 'saml'
++ strategy: 'enterprise_sso'
+```

package/dist/versions/core-3/changes/set-active-before-emit-removed.md

@@ -0,0 +1,22 @@
+---
+title: '`setActive({ beforeEmit })` changed to `setActive({ navigate })`'
+matcher: 'beforeEmit'
+category: 'deprecation-removal'
+---
+
+The `beforeEmit` callback in `setActive()` has been replaced with `navigate`. The callback signature has also changed:
+
+```diff
+await setActive({
+  session: sessionId,
+- beforeEmit: () => {
+-   // Called before session is set
+- }
++ navigate: ({ session }) => {
++   // Called with the session object
++   return '/dashboard';
++ }
+});
+```
+
+The `navigate` callback receives an object with the `session` property and should return the URL to navigate to.

package/dist/versions/core-3/changes/show-optional-fields-default.md

@@ -0,0 +1,20 @@
+---
+title: '`showOptionalFields` now defaults to `false`'
+matcher: 'showOptionalFields'
+category: 'behavior-change'
+warning: true
+---
+
+The default value of `appearance.layout.showOptionalFields` (now `appearance.options.showOptionalFields`) has changed from `true` to `false`. Optional fields are now hidden by default during sign up.
+
+To restore the previous behavior, explicitly set the option:
+
+```jsx
+<ClerkProvider
+  appearance={{
+    options: {
+      showOptionalFields: true,
+    }
+  }}
+>
+```

package/dist/versions/core-3/changes/ui-themes-export-path.md

@@ -0,0 +1,16 @@
+---
+title: 'UI themes moved to `@clerk/ui/themes/experimental`'
+matcher:
+  - '__experimental_createTheme'
+  - 'experimental_createTheme'
+category: 'breaking'
+---
+
+The `createTheme` theme utility has been moved to a new export path. Update your imports:
+
+```diff
+- import { __experimental_createTheme } from '@clerk/ui';
++ import { createTheme } from '@clerk/ui/themes/experimental';
+```
+
+Note: The `__experimental_` prefix has been removed from the method since they're now in the `/themes/experimental` subpath.

package/dist/versions/core-3/changes/unstable-to-internal.md

@@ -0,0 +1,25 @@
+---
+title: '`__unstable_*` methods renamed to `__internal_*`'
+matcher: '__unstable_'
+category: 'breaking'
+---
+
+All `__unstable_*` methods have been renamed to `__internal_*`. These are internal APIs not intended for public use.
+
+### @clerk/clerk-js
+
+- `__unstable__environment` → `__internal_environment`
+- `__unstable__updateProps` → `__internal_updateProps`
+- `__unstable__setEnvironment` → `__internal_setEnvironment`
+- `__unstable__onBeforeRequest` → `__internal_onBeforeRequest`
+- `__unstable__onAfterResponse` → `__internal_onAfterResponse`
+- `__unstable__onBeforeSetActive` → `__internal_onBeforeSetActive`
+- `__unstable__onAfterSetActive` → `__internal_onAfterSetActive`
+
+### @clerk/nextjs
+
+- `__unstable_invokeMiddlewareOnAuthStateChange` → `__internal_invokeMiddlewareOnAuthStateChange`
+
+### @clerk/chrome-extension
+
+- `__unstable__createClerkClient` → `createClerkClient` (exported from `@clerk/chrome-extension/background`)

package/dist/versions/core-3/changes/user-settings-saml-renamed.md

@@ -0,0 +1,13 @@
+---
+title: '`UserSettings.saml` renamed to `enterpriseSSO`'
+matcher: 'UserSettings[\\s\\S]*?saml'
+matcherFlags: 'm'
+category: 'deprecation-removal'
+---
+
+The `saml` property on `UserSettings` has been renamed to `enterpriseSSO`:
+
+```diff
+- userSettings.saml
++ userSettings.enterpriseSSO
+```

package/dist/versions/core-3/changes/userbutton-signout-props-removed.md

@@ -0,0 +1,26 @@
+---
+title: '`UserButton` sign-out redirect props removed'
+matcher: '<UserButton[\\s\\S]*?(afterSignOutUrl|signOutUrl)[\\s\\S]*?>'
+matcherFlags: 'm'
+category: 'deprecation-removal'
+---
+
+The `UserButton` component no longer accepts sign-out redirect override props. Configure sign-out redirects using one of these methods:
+
+**Global configuration:**
+
+```jsx
+<ClerkProvider afterSignOutUrl="/signed-out">
+```
+
+**Per-button with SignOutButton:**
+
+```jsx
+<SignOutButton redirectUrl='/goodbye'>Sign Out</SignOutButton>
+```
+
+**Programmatic:**
+
+```js
+clerk.signOut({ redirectUrl: '/signed-out' });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerk/upgrade",
-  "version": "2.0.0-snapshot.v20251208202852",
+  "version": "2.0.0-snapshot.v20251215203425",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/clerk/javascript.git",
@@ -24,7 +24,6 @@
     "chalk": "^5.3.0",
     "ejs": "3.1.10",
     "execa": "9.4.1",
-    "globby": "^14.0.1",
     "gray-matter": "^4.0.3",
     "index-to-position": "^0.1.2",
     "jscodeshift": "^17.0.0",
@@ -32,7 +31,8 @@
     "meow": "^11.0.0",
     "read-pkg": "^9.0.1",
     "semver-regex": "^4.0.5",
-    "temp-dir": "^3.0.0"
+    "temp-dir": "^3.0.0",
+    "tinyglobby": "^0.2.15"
   },
   "devDependencies": {
     "@babel/cli": "^7.24.7",
@@ -51,6 +51,7 @@
     "dev": "babel --keep-file-extension --out-dir=dist --watch src --copy-files",
     "format": "node ../../scripts/format-package.mjs",
     "format:check": "node ../../scripts/format-package.mjs --check",
+    "generate-guide": "node scripts/generate-guide.js",
     "lint": "eslint src/",
     "lint:publint": "publint",
     "test": "vitest run",