@clerk/upgrade 0.2.0 → 0.3.0

package/dist/guide-generators/v5/backend/__output.mdx

@@ -0,0 +1,580 @@
+---
+title: "Upgrading Backend to Core 2"
+description: "Learn how to upgrade Clerk's Backend SDK to the latest version."
+---
+
+# Upgrading `@clerk/backend` to Core 2
+
+Clerk's Core 2 release includes a new major version of the Backend SDK, v1. This new version ships with a variety of smaller DX improvements and housekeeping items. Each of the potentially breaking changes are detailed in this guide, below.
+
+By the end of this guide, you’ll have successfully upgraded your Backend project to use `@clerk/backend` v1. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations. Step-by-step instructions will lead you through the process.
+
+## Preparing to upgrade
+
+Before uprading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (`npm i @clerk/backend@core-1`). Some changes required for Core 2 can be applied incrementally to the latest v1 release, which should contribute to a smoother upgrading experience.
+
+After updating, look out for deprecation messages in your terminal and browser console. By resolving these deprecations you'll be able to skip many breaking changes from Core 2.
+
+<Callout>
+  Note that Core 2 is currently in beta, while we field feedback and ensure stability. Deploying beta versions to
+  production is not recommended and should be done at your own risk.
+</Callout>
+
+Additionally, some of the minumum version requirements for some base dependencies have been updated such that versions that are no longer supported or are at end-of-life are no longer guaranteed to work correctly with Clerk.
+
+**Updating Node.js**
+
+You need to have Node.js `18.17.0` or later installed. Last year, Node.js 16 entered EOL (End of life) status, so support for this version has been removed across Clerk SDKs. You can check your Node.js version by running `node -v` in your terminal. Learn more about how to [update and install Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs).
+
+## Updating to Core 2 Beta
+
+Whenever you feel ready, go ahead and install the latest beta version of any Clerk SDKs you are using. Make sure that you are prepared to patch some breaking changes before your app will work properly, however. The commands below demonstrate how to install the latest beta.
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+    ```bash filename="terminal"
+    npm install @clerk/backend@beta
+    ```
+
+    ```bash filename="terminal"
+    yarn add @clerk/backend@beta
+    ```
+
+    ```bash filename="terminal"
+    pnpm add @clerk/backend@beta
+    ```
+
+</CodeBlockTabs>
+
+## CLI Upgrade Helper
+
+As of this major version Clerk provides a `@clerk/upgrade` CLI tool that you can use to ease the upgrade. A CLI prompt will ask you a couple of questions, it will scan your codebase, and afterwards you'll get a list of changes you'll need to apply to your project, as well as the locations where they need to be applied. This should catch the vast majority of the changes needed for a successful upgrade, and can save a lot of time reading through changes to things that aren't actually in your project.
+
+To run the CLI tool, navigate to your project and run it in the terminal:
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+  ```bash filename="terminal"
+  npx @clerk/upgrade
+  ```
+
+```bash filename="terminal"
+yarn dlx @clerk/upgrade
+```
+
+```bash filename="terminal"
+pnpm dlx @clerk/upgrade
+```
+
+</CodeBlockTabs>
+
+If you are having trouble with `npx`, it's also possible to install directly with `npm i @clerk/upgrade -g`, and can then be run with the `clerk-upgrade` command.
+
+## Breaking Changes
+
+### `request` separated from `options` as params to `authenticateRequest`
+
+There has been a change to the way the params of the `authenticateRequest` function are structured. The `request` param, formerly included in an `options` object, has been moved to stand on its own as the first param to the function, while the `options` object remains as the second param. Example below:
+
+```diff
+- clerkClient.authenticateRequest({ ...opts, request })
++ clerkClient.authenticateRequest(request, { ...opts })
+```
+
+### `clockSkewInSeconds` -> `clockSkewInMs`
+
+The `clockSkewInSeconds` option has been renamed to `clockSkewInMs` in order to accurately reflect that its value is expected to be in milliseconds rather than seconds. The value does not need to change here, only the name. This change affects the following imports:
+
+- `verifyJwt`
+- `verifyToken`
+- `Clerk.authenticateRequest`
+
+### Import paths changes
+
+Some top level import paths have been changed in order to improve tree-shaking and more clearly categorize sets of functionality. Some methods have been moved under an `/internal` path, indicating that they are only intended for internal use, are exempt from semver, and should be used with great caution.
+
+<Accordion titles={["<code>verifyJwt</code> import moved to <code>@clerk/backend/tokens</code>", "<code>decodeJwt</code> import moved to <code>@clerk/backend/tokens</code>", "<code>signJwt</code> import moved to <code>@clerk/backend/tokens</code>", "<code>constants</code> import moved to <code>@clerk/backend/internal</code>", "<code>redirect</code> import moved to <code>@clerk/backend/internal</code>", "<code>createAuthenticateRequest</code> import moved to <code>@clerk/backend/internal</code>", "<code>createIsomorphicRequest</code> import moved to <code>@clerk/backend/internal</code>", "<code>createIsomorphicRequest</code> import moved to <code>/internal</code>", "<code>SignJWTError</code> import moved to <code>@clerk/backend/errors</code>", "<code>TokenVerificationError</code> import moved to <code>@clerk/backend/errors</code>", "<code>TokenVerificationErrorAction</code> import moved to <code>@clerk/backend/errors</code>", "<code>TokenVerificationErrorReason</code> import moved to <code>@clerk/backend/errors</code>"]}>
+  <AccordionPanel>    
+    The `verifyJwt` import path has changed from `@clerk/backend` to `@clerk/backend/tokens`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made
+    
+    ```diff
+    - import { verifyJwt } from "@clerk/backend"
+    + import { verifyJwt } from "@clerk/backend/tokens"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `decodeJwt` import path has changed from `@clerk/backend` to `@clerk/backend/tokens`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made
+    
+    ```diff
+    - import { decodeJwt } from "@clerk/backend"
+    + import { decodeJwt } from "@clerk/backend/tokens"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `signJwt` import path has changed from `@clerk/backend` to `@clerk/backend/tokens`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made
+    
+    ```diff
+    - import { signJwt } from "@clerk/backend"
+    + import { signJwt } from "@clerk/backend/tokens"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `constants` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { constants } from "@clerk/backend"
+    + import { constants } from "@clerk/backend/internal"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `redirect` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { redirect } from "@clerk/backend"
+    + import { redirect } from "@clerk/backend/internal"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `createAuthenticateRequest` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { createAuthenticateRequest } from "@clerk/backend"
+    + import { createAuthenticateRequest } from "@clerk/backend/internal"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `createIsomorphicRequest` import path has changed from `@clerk/backend` to `@clerk/backend/internal`. You must update your import path in order for it to work correctly. Note that internal imports are not intended for usage and are outside the scope of semver. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { createIsomorphicRequest } from "@clerk/backend"
+    + import { createIsomorphicRequest } from "@clerk/backend/internal"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `createIsomorphicRequest` import was intended for those building custom Clerk integrations for frameworks and has been moved to `@clerk/backend/internal` to reflect this. Please use caution when using internal imports as they are outside the bounds of semver.
+    
+    ```diff
+    - import { createIsomorphicRequest } from "@clerk/backend"
+    + import { createIsomorphicRequest } from "@clerk/backend/internal"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `SignJWTError` import path has changed from `@clerk/backend` to `@clerk/backend/errors`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { SignJWTError } from "@clerk/backend"
+    + import { SignJWTError } from "@clerk/backend/errors"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `TokenVerificationError` import path has changed from `@clerk/backend` to `@clerk/backend/errors`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { TokenVerificationError } from "@clerk/backend"
+    + import { TokenVerificationError } from "@clerk/backend/errors"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `TokenVerificationErrorAction` import path has changed from `@clerk/backend` to `@clerk/backend/errors`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { TokenVerificationErrorAction } from "@clerk/backend"
+    + import { TokenVerificationErrorAction } from "@clerk/backend/errors"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `TokenVerificationErrorReason` import path has changed from `@clerk/backend` to `@clerk/backend/errors`. You must update your import path in order for it to work correctly. Example below of the fix that needs to be made:
+    
+    ```diff
+    - import { TokenVerificationErrorReason } from "@clerk/backend"
+    + import { TokenVerificationErrorReason } from "@clerk/backend/errors"
+    ```
+  </AccordionPanel>
+</Accordion>
+
+### `httpOptions` parameter removed
+
+The `httpOptions` parameter was removed from the internal `buildRequest` function but it is used by most public facing APIs. Hence you were able to pass `httpOptions` to some functions which is not possible anymore. If you're currently relying on this functionality and wish to update, please reach out to Clerk's support.
+
+The internal change looks like this:
+
+```diff
+- const r = buildRequest({ httpOptions: { headers: {} }})
++ const request = buildRequest()
++ request({ headerParams: {} })
+```
+
+### Removed: `orgs` claim on JWT
+
+In the previous version of Clerk's SDKs, if you decode the session token that Clerk returns from the server, you'll currently find an `orgs` claim on it. It lists all the orgs associated with the given user. Now, Clerk returns the `org_id`, `org_slug`, and `org_role` of the **active** organization.
+
+The `orgs` claim was part of the `JwtPayload`. Here are a few examples of where the `JwtPayload` could be found.
+
+<Accordion titles={["Next.js", "Fastify", "@clerk/backend", "@clerk/clerk-sdk-node"]} heading="h5">
+  <AccordionPanel>
+    ```typescript filename="Next.js"
+    import { getAuth } from "@clerk/nextjs/server"
+    const claims: JwtPayload = getAuth(request).sessionClaims
+
+    import { getAuth } from "@clerk/ssr.server"
+    const claims: JwtPayload = (await getAuth(request)).sessionClaims
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    ```typescript filename="Fastify"
+    import { getAuth } from "@clerk/fastify"
+    const claims: JwtPayload = (await getAuth(request)).sessionClaims
+    ```
+  </AccordionPanel>
+  <AccordionPanel>
+    ```typescript filename="@clerk/backend"
+    import { createClerkClient } from "@clerk/backend"
+
+    const clerkClient = createClerkClient({ secretKey: "" })
+    const requestState = await clerkClient.authenticateRequest(
+      request,
+      { publishableKey: "" }
+    )
+    const claims: JwtPayload = requestState.toAuth().sessionClaims
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    ```typescript filename="@clerk/clerk-sdk-node"
+    import { clerkClient } from "@clerk/clerk-sdk-node"
+
+    router.use((...args) => clerkClient.expressRequireAuth()(...args))
+    router.get("/me", async (req, reply: Response) => {
+      return reply.json({ auth: req.auth })
+    })
+    ```
+
+  </AccordionPanel>
+</Accordion>
+
+If you would like to have your JWT return all of the user's organizations, you can create a [custom JWT template](/docs/backend-requests/making/jwt-templates) in your dashboard. Add `{ "orgs": "user.organizations" }` to it.
+
+### Changes to pagination arguments for some functions
+
+There were some changes made to pagination-related arguments passed into functions, in order to make it more clear how to control paginated results. See each function impacted by these changes below:
+
+<Accordion titles={["<code>Organization.getRoles</code> arguments changed", "<code>Organization.getMemberships</code> arguments changed", "<code>Organization.getDomains</code> arguments changed", "<code>Organization.getInvitations</code> arguments changed", "<code>Organization.getMembershipRequests</code> arguments changed", "<code>User.getOrganizationInvitations</code> arguments changed", "<code>User.getOrganizationSuggestions</code> arguments changed", "<code>User.getOrganizationMemberships</code> arguments changed"]}>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await organization.getRoles({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await organization.getMemberships({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await organization.getDomains({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await organization.getInvitations({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await organization.getMembershipRequests({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await user.getOrganizationInvitations({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await user.getOrganizationSuggestions({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    There have been a couple changes to the pagination arguments that can be passed into this function - `limit` has been renamed to `pageSize`, and `offset` has been renamed to `initialPage`. This will help to make it more clear and simple to reason about pagination control. Example of how changes might look below:
+    
+    ```diff
+      const { data } = await user.getOrganizationMemberships({
+    -   limit: 10,
+    +   pageSize: 10,
+    -   offset: 10,
+    +   initialPage: 2,
+      })
+    ```
+  </AccordionPanel>
+</Accordion>
+
+### Changes to some function return signatures
+
+There have been changes to return signatures for some functions. Since Clerk's API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily. This change also aligns the response shape with what is returned from the Clerk backend API. Each impacted function is listed below, along with code examples:
+
+<Accordion titles={["<code>Users.getOrganizationInvitationList</code> return signature changed", "<code>Organizations.getOrganizationInvitationList</code> return type changed", "<code>User.getOrganizationMembershipList</code> return type changed", "<code>Users.getOrganizationList</code> return signature changed", "<code>Organization.getOrganizationList</code> return type changed", "<code>Users.getOrganizationMembershipList</code> return signature changed"]}>
+  <AccordionPanel>    
+    The response payload of `Users.getOrganizationInvitationList` was changed as part of the v5 release. Rather than directly returning ` data`, the return signature is now `{ data, totalCount }`. Since backend API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the backend API returns directly.
+    
+    Here's an example of how the response shape would change with this modification:
+    
+    ```diff
+    - const data = await clerkClient.users.getOrganizationInvitationList()
+    + const { data, totalCount } = await clerkClient.users.getOrganizationInvitationList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The return type for this function was previously `[Items]` but has now been updated to `{ data: [Items], totalCount: number }`. Since Clerk's API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily. A before/after code example can be seen below:
+    
+    ```diff
+      const data = await clerkClient.organizations.getOrganizationInvitationList({
+        organizationId: "...",
+      })
+    
+    - data.forEach(() => {})
+    + data.data.forEach(() => {})
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The return type for this function was previously `[Items]` but has now been updated to `{ data: [Items], totalCount: number }`. Since Clerk's API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily. A before/after code example can be seen below:
+    
+    ```diff
+      const { user } = useUser()
+      const membershipList = user.getOrganizationMembershipList()
+    
+    - membershipList.forEach(() => {})
+    + membershipList.data.forEach(() => {})
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `Users.getOrganizationList` was changed as part of the v5 release. Rather than directly returning ` data`, the return signature is now `{ data, totalCount }`. Since backend API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the backend API returns directly.
+    
+    Here's an example of how the response shape would change with this modification:
+    
+    ```diff
+    - const data = await clerkClient.users.getOrganizationList()
+    + const { data, totalCount } = await clerkClient.users.getOrganizationList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The return type for this function was previously `[Items]` but has now been updated to `{ data: [Items], totalCount: number }`. Since Clerk's API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily. A before/after code example can be seen below:
+    
+    ```diff
+      const { organization } = useOrganization()
+      const orgList = organization.getOrganizationList()
+    
+    - orgList.forEach(() => {})
+    + orgList.data.forEach(() => {})
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `Users.getOrganizationMembershipList` was changed as part of the v5 release. Rather than directly returning ` data`, the return signature is now `{ data, totalCount }`. Since backend API responses are paginated, the `totalCount` property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the backend API returns directly.
+    
+    Here's an example of how the response shape would change with this modification:
+    
+    ```diff
+    - const data = await clerkClient.users.getOrganizationMembershipList()
+    + const { data, totalCount } = await clerkClient.users.getOrganizationMembershipList()
+    ```
+  </AccordionPanel>
+</Accordion>
+
+### Image URL Name Consolidation
+
+There are a number of Clerk primitives that contain images, and previously they each had different property names, like `avatarUrl`, `logoUrl`, `profileImageUrl`, etc. In order to promote consistency and make it simpler for developers to know where to find associated images, all image properties are now named `imageUrl`. See the list below for all affected classes:
+
+<Accordion titles={["<code>Organization.logoUrl</code> -&gt; <code>Organization.imageUrl</code>", "<code>User.profileImageUrl</code> -&gt; <code>.imageUrl</code>", "<code>ExternalAccount.picture</code> -&gt; <code>.imageUrl</code>", "<code>ExternalAccountJSON.avatar_url</code> -&gt; <code>.imageUrl</code>", "<code>OrganizationJSON.logo_url</code> -&gt; <code>.imageUrl</code>", "<code>UserJSON.profile_image_url</code> -&gt; <code>.imageUrl</code>", "<code>OrganizationMembershipPublicUserData.profileImageUrl</code> -&gt; <code>.imageUrl</code>", "<code>OrganizationMembershipPublicUserDataJSON.profile_image_url</code> -&gt; <code>.imageUrl</code>"]}>
+  <AccordionPanel>    
+    The `logoUrl` property of any [`Organization` object](https://clerk.com/docs/references/javascript/organization/organization#organization) has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profileImageUrl` property of any `User` object has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `picture` property of any [`ExternalAcccount` object](https://clerk.com/docs/references/javascript/external-account) has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `avatarUrl` property of any `ExternalAcccountJSON` object has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `logo_url` property of any `OrganizationJSON` object has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profile_image_url` property of any `UserJSON` object has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profileImageUrl` property of any `OrganizationMembershipPublicUserData` object has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profile_image_url` property of any `OrganizationMembershipPublicUserDataJSON` object has been changed to `imageUrl`.
+  </AccordionPanel>
+</Accordion>
+
+### Deprecation removals & housekeeping
+
+As part of this major version, a number of previously deprecated props, arugments, methods, etc have been removed. Additionally there have been some changes to things that are only used internally, or only used very rarely. It's highly unlikely that any given app will encounter any of these items, but they are all breaking changes, so they have all been documented below.
+
+<Callout type='info'>
+  For this section more than any other one, please use the CLI upgrade tool (`npx @clerk/upgrade`). Changes in this
+  section are very unlikely to appear in your codebase, the tool will save time looking for them.
+</Callout>
+
+#### Deprecation removals
+
+<Accordion titles={["<code>User.update({ password: &#39;x&#39; })</code> -&gt; <code>User.updatePassword(&#39;x&#39;)</code>", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to createClerkClient", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to createClerkClient"]}>
+  <AccordionPanel>    
+    If you are updating a user's password via the [`User.update` method](https://clerk.com/docs/references/javascript/user/user#update), it must be changed to [`User.updatePassword`](https://clerk.com/docs/references/javascript/user/password-management#update-password) instead. This method will require the current password as well as the desired new password. We made this update to improve the security of password changes. Example below:
+    
+    ```diff
+    - user.update({ password: 'foo' });
+    
+    + user.updatePassword({
+    +   currentPassword: 'bar',
+    +   newPassword: 'foo',
+    +   signOutOfOtherSessions: true,
+    + });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` argument passed to `createClerkClient` must be changed to `publishableKey`. Note that the values of the two keys are different, so both keys and values need to be changed. You can find your application's publishable key in the Clerk dashboard. Also note that the import value has changed for creating a new Clerk client, which will be addressed by a separate line item if relevant to your codebase.
+    
+    ```diff
+    - import { Clerk } from '@clerk/backend';
+    + import { createClerkClient } from '@clerk/backend';
+    
+    - const clerkClient = Clerk({ frontendApi: '...' });
+    + const clerkClient = createClerkClient({ publishableKey: '...' });
+    
+    - clerkClient.authenticateRequest({ frontendApi: '...' });
+    + clerkClient.authenticateRequest({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `createClerkClient` must be changed to `secretKey`. Also note that the import value has changed for creating a new Clerk client, which will be addressed by a separate line item if relevant to your codebase.
+    
+    ```diff
+    - import { Clerk } from '@clerk/backend';
+    + import { createClerkClient } from '@clerk/backend';
+    
+    - const clerkClient = Clerk({ apiKey: '...' });
+    + const clerkClient = createClerkClient({ secretKey: '...' });
+    
+    - clerkClient.authenticateRequest({ apiKey: '...' });
+    + clerkClient.authenticateRequest({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+</Accordion>
+
+#### Other Breaking Changes
+
+<Accordion titles={["<code>API_URL</code> value has changed", "<code>Clerk</code> -&gt; <code>createClerkClient</code>", "<code>pkgVersion</code> -&gt; <code>clerkJSVersion</code>", "<code>clerkClient.__unstable_options</code> removed", "<code>createEmail</code> import removed", "<code>MembershipRole</code> type replaced by <code>OrganizationCustomRoleKey</code> type", "<code>buildRequestUrl</code> import removed"]}>
+  <AccordionPanel>    
+    The value of this export has changed from `https://api.clerk.dev` to `https://api.clerk.com`. If you were relying on the text content of this value not changing, you may need to make adjustments.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The top level `Clerk` import was renamed to `createClerkClient`. This is just a name change and can be treated as a text replacement, no changes to the params or return types.
+    
+    ```js
+    // before
+    import { Clerk } from '@clerk/backend';
+    
+    // after
+    import { createClerkClient } from '@clerk/backend';
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `pkgVersion` parameter was removed from the `loadInterstitialFromLocal`, `loadInterstitialFromBAPI`, and `buildPublicInterstitialUrl` functions. Use `clerkJSVersion` instead. Example:
+    
+    ```diff
+    - loadInterstitialFromLocal({ pkgVersion: "..." })
+    + loadInterstitialFromLocal({ clerkJSVersion: "..." })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `clerkClient.__unstable_options` property was removed. Previously, you could use it to update the internal options. Instead, create a new ` clerkClient` instance using `createClerkClient` and pass the options in this way. For example:
+    
+    ```diff
+      import { createClerkClient } from "@clerk/backend"
+    
+      const clerkClient = createClerkClient({ secretKey: "old" })
+    
+    - clerkClient.__unstable_options.secretKey = "new"
+    + const newClerkClient = createClerkClient({ secretKey: "new" })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `createEmail` import has been removed. There is no replacement at this time because we need to rethink how `createEmail` behaves and align it with the newer `sendSms` method. If this is an issue for your implementation, please contact [Clerk support](https://clerk.com/contact).
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `MembershipRole` type was replaced with `OrganizationCustomRoleKey` (related to [roles and permissions](https://clerk.com/docs/organizations/roles-permissions)). An example of where this type might be found:
+    
+    ```js
+    import { useAuth } from '@clerk/clerk-react';
+    
+    const { orgRole } = useAuth();
+    ```
+    
+    To support the existing roles `admin`, `basic_member`, and `guest_member` apply interface merging using the following snippet:
+    
+    ```js
+    interface ClerkAuthorization {
+      permission: ''
+      role: 'admin' | 'basic_member' | 'guest_member'
+    }
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `buildRequestUrl` import was intended for those building custom Clerk integrations for frameworks and has been removed in favor of other methods internally. If you were relying on this function and this is an issue, please [reach out to Clerk support](https://clerk.com/support).
+  </AccordionPanel>
+</Accordion>
+
+
+

package/dist/guide-generators/v5/backend/import-moves.mdx

@@ -0,0 +1,3 @@
+## Some import paths changes
+
+Some top level import paths have been changed in order to improve tree-shaking and more clearly categorize sets of functionality. Some methods have been moved under an `/internal` path, indicating that they are only intended for internal use, are exempt from semver, and should be used with great caution.

package/dist/guide-generators/v5/backend/import-paths.mdx

@@ -0,0 +1,3 @@
+### Import paths changes
+
+Some top level import paths have been changed in order to improve tree-shaking and more clearly categorize sets of functionality. Some methods have been moved under an `/internal` path, indicating that they are only intended for internal use, are exempt from semver, and should be used with great caution.

package/dist/guide-generators/v5/backend/index.js

@@ -0,0 +1,22 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'v5';
+const name = 'backend';
+const properName = 'Backend';
+const packageName = '@clerk/backend';
+const cwd = `${version}/${name}`;
+async function generate() {
+  const data = await loadVersionChangeData(version, name);
+  return assembleContent({
+    data,
+    cwd
+  }, [frontmatter({
+    title: `Upgrading ${properName} to Core 2`,
+    description: `Learn how to upgrade Clerk's ${properName} SDK to the latest version.`
+  }), `# Upgrading \`${packageName}\` to Core 2`, markdown('intro'), markdownTemplate('prepare', {
+    version: 'v1',
+    packageName
+  }), markdown('node-version'), markdownTemplate('update-version', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', singleItem('authenticaterequest-params-change'), singleItem('clockskewinseconds'), markdown('import-paths'), accordionForCategory('import-paths'), singleItem('httpoptions-removed'), markdown('orgs-claim'), markdown('pagination-args'), accordionForCategory('pagination-args'), markdown('pagination-return'), accordionForCategory('pagination-return'), markdown('image-url'), accordionForCategory(['image-url', 'image-url-backend']), deprecationRemovalsAndHousekeeping()]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/v5/backend/intro.mdx

@@ -0,0 +1,3 @@
+Clerk's Core 2 release includes a new major version of the Backend SDK, v1. This new version ships with a variety of smaller DX improvements and housekeeping items. Each of the potentially breaking changes are detailed in this guide, below.
+
+By the end of this guide, you’ll have successfully upgraded your Backend project to use `@clerk/backend` v1. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations. Step-by-step instructions will lead you through the process.

package/dist/guide-generators/v5/chrome-extension/index.js

@@ -0,0 +1,19 @@
+import { accordionForCategory, assembleContent, deprecationRemovalsAndHousekeeping, frontmatter, loadVersionChangeData, markdown, markdownTemplate, singleItem, writeToFile } from '../../text-generation.js';
+const version = 'v5';
+const name = 'chrome-extension';
+const properName = 'Chrome Extension';
+const packageName = '@clerk/chrome-extension';
+const cwd = `${version}/chromeExtension`;
+async function generate() {
+  const data = loadVersionChangeData(version, name);
+  return assembleContent({
+    data,
+    cwd
+  }, [frontmatter({
+    title: `Upgrading ${properName} SDK from v4 to v5`,
+    description: `Learn how to upgrade Clerk's ${properName} SDK from v4 to v5.`
+  }), `# Upgrading \`${packageName}\` from v4 to v5`, markdown('intro'), markdown('prepare'), markdown('node-version'), markdown('react-version'), markdownTemplate('update-v5', {
+    packageName
+  }), markdown('cli'), '## Breaking Changes', singleItem('clerkprovider-tokencache'), markdown('redesign-preview'), markdown('after-sign-x-handling'), singleItem('navigate-to-routerpush-routerreplace'), markdown('orgs-claim'), markdown('path-routing'), markdown('image-url'), accordionForCategory('image-url'), deprecationRemovalsAndHousekeeping()]);
+}
+generate().then(writeToFile(cwd));

package/dist/guide-generators/v5/chrome-extension/intro.mdx

@@ -0,0 +1,3 @@
+Version 5 of the Chrome Extension SDK ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, and a variety of smaller DX improvements and housekeeping items. Each of the potentially breaking changes are detailed in this guide, below.
+
+By the end of this guide, you’ll have successfully upgraded your project to use `@clerk/chrome-extension` v5. You’ll learn how to update your dependencies, resolve breaking changes, and find deprecations. Step-by-step instructions will lead you through the process.