@clerk/upgrade 2.0.0-snapshot.v20251204175016 → 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/expo-old-package/package-lock.json

@@ -0,0 +1,5 @@
+{
+  "name": "test-expo-old",
+  "lockfileVersion": 3
+}
+

package/dist/__tests__/fixtures/expo-old-package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "test-expo-old",
+  "version": "1.0.0",
+  "dependencies": {
+    "@clerk/clerk-expo": "^2.0.0",
+    "expo": "^50.0.0",
+    "react": "^18.0.0",
+    "react-native": "^0.73.0"
+  }
+}

package/dist/__tests__/fixtures/expo-old-package/src/App.tsx

@@ -0,0 +1,14 @@
+import { ClerkProvider, useAuth } from '@clerk/clerk-expo';
+
+export default function App() {
+  return (
+    <ClerkProvider publishableKey='pk_test_xxx'>
+      <AuthStatus />
+    </ClerkProvider>
+  );
+}
+
+function AuthStatus() {
+  const { isSignedIn } = useAuth();
+  return <Text>{isSignedIn ? 'Signed in' : 'Signed out'}</Text>;
+}

package/dist/__tests__/fixtures/nextjs-v6/package.json

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

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

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

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

@@ -0,0 +1,17 @@
+import { ClerkProvider, useAuth } from '@clerk/nextjs';
+import { useUser } from '@clerk/clerk-react';
+
+export default function App({ children }) {
+  return <ClerkProvider>{children}</ClerkProvider>;
+}
+
+export function UserProfile() {
+  const { isSignedIn } = useAuth();
+  const { user } = useUser();
+
+  if (!isSignedIn) {
+    return <div>Not signed in</div>;
+  }
+
+  return <div>Hello, {user?.firstName}</div>;
+}

package/dist/__tests__/fixtures/nextjs-v7/package.json

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

package/dist/__tests__/fixtures/nextjs-v7/pnpm-lock.yaml

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

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

@@ -0,0 +1,16 @@
+import { ClerkProvider, useAuth, useUser } from '@clerk/nextjs';
+
+export default function App({ children }) {
+  return <ClerkProvider>{children}</ClerkProvider>;
+}
+
+export function UserProfile() {
+  const { isSignedIn } = useAuth();
+  const { user } = useUser();
+
+  if (!isSignedIn) {
+    return <div>Not signed in</div>;
+  }
+
+  return <div>Hello, {user?.firstName}</div>;
+}

package/dist/__tests__/fixtures/no-clerk/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "test-no-clerk",
+  "version": "1.0.0",
+  "dependencies": {
+    "react": "^18.0.0"
+  }
+}

package/dist/__tests__/fixtures/react-v6/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "test-react-v6",
+  "version": "1.0.0",
+  "dependencies": {
+    "@clerk/clerk-react": "^5.0.0",
+    "react": "^18.0.0"
+  }
+}

package/dist/__tests__/fixtures/react-v6/src/App.tsx

@@ -0,0 +1,19 @@
+import { ClerkProvider, useUser } from '@clerk/react';
+
+export default function App() {
+  return (
+    <ClerkProvider publishableKey='pk_test_xxx'>
+      <UserInfo />
+    </ClerkProvider>
+  );
+}
+
+function UserInfo() {
+  const { user, isSignedIn } = useUser();
+
+  if (!isSignedIn) {
+    return <div>Please sign in</div>;
+  }
+
+  return <div>Welcome, {user?.firstName}</div>;
+}

package/dist/__tests__/fixtures/react-v6/yarn.lock

@@ -0,0 +1,2 @@
+# yarn lockfile v1
+

package/dist/__tests__/helpers/create-fixture.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES_DIR = path.join(__dirname, '..', 'fixtures');
+export function getFixturePath(fixtureName) {
+  return path.join(FIXTURES_DIR, fixtureName);
+}
+export function createTempFixture(fixtureName) {
+  const sourcePath = getFixturePath(fixtureName);
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `clerk-upgrade-test-${fixtureName}-`));
+  copyDirSync(sourcePath, tempDir);
+  return {
+    path: tempDir,
+    cleanup() {
+      fs.rmSync(tempDir, {
+        recursive: true,
+        force: true
+      });
+    }
+  };
+}
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, {
+    recursive: true
+  });
+  const entries = fs.readdirSync(src, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+export function readFixtureFile(fixtureName, filePath) {
+  return fs.readFileSync(path.join(getFixturePath(fixtureName), filePath), 'utf8');
+}
+export function writeFixtureFile(tempPath, filePath, content) {
+  const fullPath = path.join(tempPath, filePath);
+  fs.mkdirSync(path.dirname(fullPath), {
+    recursive: true
+  });
+  fs.writeFileSync(fullPath, content, 'utf8');
+}
+export function readTempFile(tempPath, filePath) {
+  return fs.readFileSync(path.join(tempPath, filePath), 'utf8');
+}
+export function fileExists(tempPath, filePath) {
+  return fs.existsSync(path.join(tempPath, filePath));
+}

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

@@ -0,0 +1,275 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createTempFixture, getFixturePath } from '../helpers/create-fixture.js';
+
+// Toggle this to true to debug the CLI output during the test run
+const DEBUG_OUTPUT = false;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = path.resolve(__dirname, '../../cli.js');
+function runCli(args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', [CLI_PATH, ...args], {
+      cwd: options.cwd || process.cwd(),
+      env: {
+        ...process.env,
+        FORCE_COLOR: '0',
+        NO_COLOR: '1'
+      },
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', data => {
+      stdout += data.toString();
+      if (DEBUG_OUTPUT) {
+        console.log(data.toString());
+      }
+    });
+    child.stderr.on('data', data => {
+      stderr += data.toString();
+      if (DEBUG_OUTPUT) {
+        console.error(data.toString());
+      }
+    });
+
+    // Send input if provided (for interactive prompts)
+    if (options.input) {
+      child.stdin.write(options.input);
+      child.stdin.end();
+    }
+
+    // Set timeout to kill the process
+    const timeout = setTimeout(() => {
+      child.kill('SIGTERM');
+      resolve({
+        stdout,
+        stderr,
+        exitCode: null,
+        timedOut: true
+      });
+    }, options.timeout || 10000);
+    child.on('close', exitCode => {
+      clearTimeout(timeout);
+      resolve({
+        stdout,
+        stderr,
+        exitCode,
+        timedOut: false
+      });
+    });
+    child.on('error', err => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+describe('CLI Integration', () => {
+  describe('--help flag', () => {
+    it('displays help text', async () => {
+      const result = await runCli(['--help']);
+      expect(result.stdout).toContain('Usage');
+      expect(result.stdout).toContain('npx @clerk/upgrade');
+      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);
+    });
+  });
+  describe('--version flag', () => {
+    it('displays version', async () => {
+      const result = await runCli(['--version']);
+      expect(result.stdout).toMatch(/\d+\.\d+\.\d+/);
+      expect(result.exitCode).toBe(0);
+    });
+  });
+  describe('SDK Detection', () => {
+    it('detects nextjs SDK from project directory', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+
+      // Combine stdout and stderr for full output
+      const output = result.stdout + result.stderr;
+      expect(output).toContain('@clerk/nextjs');
+      expect(output).toContain('dry run');
+    });
+    it('detects nextjs v7 as already upgraded', async () => {
+      const dir = getFixturePath('nextjs-v7');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('@clerk/nextjs');
+      expect(result.stdout).toContain('already on the latest');
+    });
+    it('errors when SDK not detected and not provided in non-interactive mode', async () => {
+      const dir = getFixturePath('no-clerk');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 5000
+      });
+
+      // Error messages go to stderr via console.error
+      const output = result.stdout + result.stderr;
+      expect(output).toContain('Could not detect Clerk SDK');
+      expect(output).toContain('--sdk');
+      expect(result.exitCode).toBe(1);
+    });
+  });
+  describe('--sdk flag', () => {
+    it('accepts explicit SDK specification', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--sdk', 'nextjs', '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('@clerk/nextjs');
+    });
+    it('accepts @clerk/ prefixed SDK name', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--sdk', '@clerk/nextjs', '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('@clerk/nextjs');
+    });
+  });
+  describe('--dry-run flag', () => {
+    let fixture;
+    beforeEach(() => {
+      fixture = createTempFixture('nextjs-v6');
+    });
+    afterEach(() => {
+      fixture?.cleanup();
+    });
+    it('shows what would be done without making changes', async () => {
+      const result = await runCli(['--dir', fixture.path, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('[dry run]');
+    });
+    it('does not modify package.json in dry-run mode', async () => {
+      const fs = await import('node:fs');
+      const pkgBefore = fs.readFileSync(path.join(fixture.path, 'package.json'), 'utf8');
+      await runCli(['--dir', fixture.path, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      const pkgAfter = fs.readFileSync(path.join(fixture.path, 'package.json'), 'utf8');
+      expect(pkgAfter).toBe(pkgBefore);
+    });
+  });
+  describe('Version Display', () => {
+    it('shows current version in output', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('v6');
+    });
+    it('shows upgrade path in output', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('v6 → v7');
+    });
+  });
+  describe('Package Manager Detection', () => {
+    it('detects pnpm from fixture', async () => {
+      const dir = getFixturePath('nextjs-v6');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('pnpm');
+    });
+    it('detects yarn from fixture', async () => {
+      const dir = getFixturePath('react-v6');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toMatch(/yarn/i);
+    });
+    it('detects npm from fixture', async () => {
+      const dir = getFixturePath('expo-old-package');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toMatch(/npm/i);
+    });
+  });
+  describe('Legacy Package Names', () => {
+    it('handles @clerk/clerk-react legacy package', async () => {
+      const dir = getFixturePath('react-v6');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('@clerk/react');
+    });
+    it('handles @clerk/clerk-expo legacy package', async () => {
+      const dir = getFixturePath('expo-old-package');
+      const result = await runCli(['--dir', dir, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      expect(result.stdout).toContain('@clerk/expo');
+    });
+  });
+  describe('Codemods', () => {
+    let fixture;
+    beforeEach(() => {
+      fixture = createTempFixture('nextjs-v6');
+    });
+    afterEach(() => {
+      fixture?.cleanup();
+    });
+    it('lists codemods that would run in dry-run mode', async () => {
+      const result = await runCli(['--dir', fixture.path, '--dry-run', '--skip-codemods'], {
+        timeout: 15000
+      });
+      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

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { getOldPackageName, getTargetPackageName, loadConfig } from '../../config.js';
+describe('loadConfig', () => {
+  it('returns config with needsUpgrade: true for nextjs v6', async () => {
+    const config = await loadConfig('nextjs', 6);
+    expect(config).not.toBeNull();
+    expect(config.id).toBe('core-3');
+    expect(config.needsUpgrade).toBe(true);
+    expect(config.alreadyUpgraded).toBe(false);
+  });
+  it('returns config with alreadyUpgraded: true for nextjs v7', async () => {
+    const config = await loadConfig('nextjs', 7);
+    expect(config).not.toBeNull();
+    expect(config.id).toBe('core-3');
+    expect(config.needsUpgrade).toBe(false);
+    expect(config.alreadyUpgraded).toBe(true);
+  });
+  it('returns config with needsUpgrade: true for react v6', async () => {
+    const config = await loadConfig('react', 6);
+    expect(config).not.toBeNull();
+    expect(config.needsUpgrade).toBe(true);
+  });
+  it('returns config with needsUpgrade: true for expo v2', async () => {
+    const config = await loadConfig('expo', 2);
+    expect(config).not.toBeNull();
+    expect(config.needsUpgrade).toBe(true);
+  });
+  it('returns null for unsupported SDK version (too old)', async () => {
+    const config = await loadConfig('nextjs', 4);
+    expect(config).toBeNull();
+  });
+  it('loads codemods array from config', async () => {
+    const config = await loadConfig('nextjs', 6);
+    expect(config.codemods).toBeDefined();
+    expect(Array.isArray(config.codemods)).toBe(true);
+    expect(config.codemods.length).toBeGreaterThan(0);
+  });
+  it('loads changes array from config', async () => {
+    const config = await loadConfig('nextjs', 6);
+    expect(config.changes).toBeDefined();
+    expect(Array.isArray(config.changes)).toBe(true);
+  });
+  it('includes docsUrl in config', async () => {
+    const config = await loadConfig('nextjs', 6);
+    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', () => {
+    expect(getTargetPackageName('react')).toBe('@clerk/react');
+  });
+  it('returns @clerk/react for clerk-react sdk', () => {
+    expect(getTargetPackageName('clerk-react')).toBe('@clerk/react');
+  });
+  it('returns @clerk/expo for expo sdk', () => {
+    expect(getTargetPackageName('expo')).toBe('@clerk/expo');
+  });
+  it('returns @clerk/expo for clerk-expo sdk', () => {
+    expect(getTargetPackageName('clerk-expo')).toBe('@clerk/expo');
+  });
+  it('returns @clerk/nextjs for nextjs sdk', () => {
+    expect(getTargetPackageName('nextjs')).toBe('@clerk/nextjs');
+  });
+});
+describe('getOldPackageName', () => {
+  it('returns @clerk/clerk-react for react sdk', () => {
+    expect(getOldPackageName('react')).toBe('@clerk/clerk-react');
+  });
+  it('returns @clerk/clerk-expo for expo sdk', () => {
+    expect(getOldPackageName('expo')).toBe('@clerk/clerk-expo');
+  });
+  it('returns null for nextjs sdk (no rename)', () => {
+    expect(getOldPackageName('nextjs')).toBeNull();
+  });
+});