Changelog · Report a Bug · Request a Feature · Get help

Getting Started

A tool that helps with upgrading major versions of Clerk's SDKs.

Prerequisites

• Node.js >=18.17.0 or later

Usage

Navigate to the application you want to upgrade and run the following in your terminal:

npx @clerk/upgrade

Fill out the questionnaire and the CLI will show you the required changes.

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.

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.

It will also be very likely to miss if you bind a method on an object to a separate variable and call it from there, or pass a bound method through a function param. For example, something like this:

const updateUser = user.update.bind(user);

updateUser({ username: 'foo' });

Overall, there's a very good chance that this tool catches everything, but it's not a guarantee. Make sure that you also test your app before deploying, and that you have good E2E test coverage.

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• On our support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.

Security

@clerk/upgrade follows good practices of security, but 100% security cannot be assured.

@clerk/upgrade is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.