@clerk/upgrade 2.0.0-canary.v20251209192855 → 2.0.0-canary.v20251209195031
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -27,25 +27,55 @@
|
|
|
27
27
|
|
|
28
28
|
## Getting Started
|
|
29
29
|
|
|
30
|
-
A
|
|
30
|
+
A CLI that detects your installed Clerk SDK, upgrades packages to the next major release, runs codemods, and scans your codebase for breaking changes.
|
|
31
31
|
|
|
32
32
|
### Prerequisites
|
|
33
33
|
|
|
34
|
-
- Node.js `>=
|
|
34
|
+
- Node.js `>=20.9.0`
|
|
35
|
+
- pnpm, npm, or yarn installed in the target project
|
|
35
36
|
|
|
36
37
|
## Usage
|
|
37
38
|
|
|
38
|
-
|
|
39
|
+
Run the CLI from the root of the project you want to upgrade:
|
|
39
40
|
|
|
40
41
|
```sh
|
|
42
|
+
# with pnpm
|
|
43
|
+
pnpm dlx @clerk/upgrade
|
|
44
|
+
|
|
45
|
+
# with npm
|
|
41
46
|
npx @clerk/upgrade
|
|
47
|
+
|
|
48
|
+
# if installed locally
|
|
49
|
+
pnpm clerk-upgrade
|
|
42
50
|
```
|
|
43
51
|
|
|
44
|
-
Fill out the
|
|
52
|
+
Fill out the prompts and the CLI will:
|
|
53
|
+
|
|
54
|
+
- Detect your Clerk SDK and version (or prompt for `--sdk`)
|
|
55
|
+
- Upgrade packages (including renames such as `@clerk/clerk-react` → `@clerk/react`)
|
|
56
|
+
- Run codemods for the selected release
|
|
57
|
+
- Scan your files for breaking changes and print a report
|
|
58
|
+
|
|
59
|
+
### CLI options
|
|
60
|
+
|
|
61
|
+
- `--sdk` — SDK to upgrade (e.g., `nextjs`, `react`, `expo`); required in non-interactive runs if detection fails
|
|
62
|
+
- `--dir` — directory to scan (default: current working directory)
|
|
63
|
+
- `--glob` — glob of files for codemods (default: `**/*.(js|jsx|ts|tsx|mjs|cjs)`)
|
|
64
|
+
- `--ignore` — extra globs to ignore during scans (repeatable)
|
|
65
|
+
- `--release` — target release (e.g., `core-3`); otherwise auto-selected from installed versions
|
|
66
|
+
- `--skip-upgrade` — skip installing/updating packages
|
|
67
|
+
- `--skip-codemods` — skip codemod execution
|
|
68
|
+
- `--dry-run` — show what would change without writing or installing
|
|
69
|
+
|
|
70
|
+
### Releases
|
|
71
|
+
|
|
72
|
+
- `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
|
|
73
|
+
|
|
74
|
+
The CLI selects the appropriate release automatically based on the installed major version, or you can pin a release with `--release` (currently `core-3`).
|
|
45
75
|
|
|
46
76
|
### Caveats
|
|
47
77
|
|
|
48
|
-
|
|
78
|
+
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.
|
|
49
79
|
|
|
50
80
|
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.
|
|
51
81
|
|