fix(upgrade): Update README.md

[jacekradko]

Description

Updating the README.md for @clerk/upgrade

Related #7385

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Documentation
  • Enhanced CLI tool documentation with detailed usage instructions and prerequisites (Node.js >=20.9.0).
  • Added comprehensive CLI options reference including flags for sdk, dir, glob, ignore, release, skip-upgrade, skip-codemods, and dry-run.
  • Included release information, examples, and important caveats about tool limitations and testing recommendations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 034cf70

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/upgrade	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Dec 9, 2025 4:35pm

[coderabbitai]

Walkthrough

A new changeset file was created for a patch release of @clerk/upgrade, and the package's README was substantially expanded with detailed documentation covering CLI usage, options, release information, and tool limitations.

Changes

Cohort / File(s)	Summary
Changeset .changeset/metal-badgers-refuse.md	New changeset entry for @clerk/upgrade patch release with note to update README
Documentation packages/upgrade/README.md	Comprehensive README expansion: updated prerequisites (Node.js >=20.9.0), reframed usage instructions with explicit installation commands, added detailed CLI prompts flow, new CLI options section (sdk, dir, glob, ignore, release, skip-upgrade, skip-codemods, dry-run), Releases section with core-3 upgrade details, and expanded caveats on regex limitations, bound methods, and testing importance

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• README comprehensiveness: Verify that all CLI options, flags, and release information are accurate and complete
• Clarity and examples: Ensure the expanded usage instructions, prompts flow, and examples are clear and comprehensive
• Caveats accuracy: Confirm that warnings about regex-based scanning, bound methods, and edge cases are correct and helpful

Poem

🐰 A tool that upgrades with might,
Detecting SDKs left and right,
Our README now shines so bright,
With options, flows, and caveats tight—
Hop along, the docs take flight! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(upgrade): Update README.md' directly corresponds to the primary change in the pull request, which is updating the README.md file for @clerk/upgrade with comprehensive documentation improvements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/upgrade-readme

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 2b1f9d1 and 034cf70.

📒 Files selected for processing (2)

• .changeset/metal-badgers-refuse.md (1 hunks)
• packages/upgrade/README.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{js,jsx,ts,tsx,json,md,yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use Prettier for consistent code formatting

Files:

• packages/upgrade/README.md

**/README.md

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Provide usage examples in documentation

Files:

• packages/upgrade/README.md

packages/*/README.md

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

packages/*/README.md: Maintain up-to-date README files for each package
Maintain compatibility matrices for supported versions

Files:

• packages/upgrade/README.md

**/*.{md,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Update documentation for API changes

Files:

• packages/upgrade/README.md

**/*.{js,ts,jsx,tsx,json,md,yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Use Prettier for code formatting across all packages

Files:

• packages/upgrade/README.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (29)

• GitHub Check: Publish with pkg-pr-new
• GitHub Check: Static analysis
• GitHub Check: Unit Tests (shared, clerk-js, RQ)
• GitHub Check: Unit Tests (**)
• GitHub Check: Integration Tests (billing, chrome, RQ)
• GitHub Check: Integration Tests (quickstart, chrome, 15)
• GitHub Check: Integration Tests (nextjs, chrome, 16)
• GitHub Check: Integration Tests (machine, chrome, RQ)
• GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
• GitHub Check: Integration Tests (quickstart, chrome, 16)
• GitHub Check: Integration Tests (machine, chrome)
• GitHub Check: Integration Tests (astro, chrome)
• GitHub Check: Integration Tests (localhost, chrome)
• GitHub Check: Integration Tests (billing, chrome)
• GitHub Check: Integration Tests (nextjs, chrome, 15)
• GitHub Check: Integration Tests (react-router, chrome)
• GitHub Check: Integration Tests (nuxt, chrome)
• GitHub Check: Integration Tests (vue, chrome)
• GitHub Check: Integration Tests (custom, chrome)
• GitHub Check: Integration Tests (handshake:staging, chrome)
• GitHub Check: Integration Tests (tanstack-react-start, chrome)
• GitHub Check: Integration Tests (ap-flows, chrome)
• GitHub Check: Integration Tests (express, chrome)
• GitHub Check: Integration Tests (handshake, chrome)
• GitHub Check: Integration Tests (sessions, chrome)
• GitHub Check: Integration Tests (sessions:staging, chrome)
• GitHub Check: Integration Tests (generic, chrome)
• GitHub Check: semgrep-cloud-platform/scan
• GitHub Check: semgrep-cloud-platform/scan

🔇 Additional comments (2)

.changeset/metal-badgers-refuse.md (1)

1-5: Changeset file format is correct.

The changeset follows standard conventions with proper YAML frontmatter and a clear description of the patch-level update.

packages/upgrade/README.md (1)

30-90: Comprehensive documentation update that significantly improves clarity and usability.

The README has been substantially expanded with essential information:

• Clear problem statement and tool capabilities (line 30)
• Explicit prerequisites and installation methods (lines 34–50)
• Step-by-step explanation of the CLI workflow (lines 52–57)
• Well-organized CLI options documentation (lines 59–68)
• Release information with auto-selection details (lines 70–74)
• Detailed caveats with concrete examples of tool limitations (lines 76–90)

The documentation now sets proper user expectations by being transparent about regex-based scanning limitations and edge cases (unusual imports, bound methods) that the tool may miss. The examples provided are helpful for advanced users who need to understand the tool's boundaries.

To ensure consistency with the actual CLI implementation, please verify that:

1. The documented Node.js requirement (>=20.9.0) matches the project's minimum supported version
2. The CLI options and their behaviors match the actual implementation
3. The core-3 release upgrade targets are current and accurate

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7413

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7413

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7413

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7413

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7413

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7413

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7413

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7413

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7413

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7413

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7413

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7413

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7413

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7413

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7413

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7413

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7413

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7413

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7413

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7413

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7413

commit: 034cf70

[brkalow]

Thanks!