How Clerk SDKs are versioned and released

Clerk is on roughly a 6 month major release cycle for its SDKs. This means that every ~6 months, there is a release cycle across all SDKs that may include breaking changes that need to be released for any given SDK. All of our SDKs use semantic versioning independently.

You may see the term "Core N" in our docs and release announcements. This refers to a set of core functionality that is included across all SDK libraries, rather than to a specific version of any individual SDK. As an example, in the Core 2 release, the Next.js SDK boosted its major version from v4 to v5. However, not every SDK had a major version increment as part of the Core 2 release.

When there is a new Core release, you can expect an upgrade guide alongside it for each Clerk SDK, and that guide will mention the SDK's current semver version. However, this is not generally something that anyone needs to be concerned with - if you want the latest version, you can just install the sdk as usual and get the latest version. The "Core N" terminology is simply a way for us at Clerk to broadly refer to a set of changes and improvements made to Clerk's functionality that is included in all of our SDKs to different extents. There is no literal SDK or Clerk library called "Core".

Whenever a new Core release is cut, the latest version of each SDK including the previous Core release will be tagged in npm, to make it simple to roll back if needed. So, for example, if Clerk released Core 2:

  • npm i @clerk/nextjs would install the latest release, which would be on top of Core 2.
  • npm i @clerk/nextjs@core-1 would install the latest version of the SDK that was released before Core 2 came out.


What did you think of this content?