@clerk/upgrade 1.0.2 → 1.0.3

package/dist/guide-generators/core-2/node/__output.mdx

@@ -0,0 +1,592 @@
+---
+title: "Upgrading Node to Core 2"
+description: "Learn how to upgrade Clerk's Node SDK to the lastest version."
+---
+
+{/* WARNING: This is a generated file and should not be edited directly. To update its contents, see the "upgrade" package in the clerk/javascript repo. */}
+
+# Upgrading `@clerk/clerk-sdk-node` to Core 2
+
+Core 2 is included in the Node.js SDK starting with version 5. 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 Node project to use `@clerk/clerk-sdk-node` 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.
+
+## Preparing to upgrade
+
+Before uprading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (`npm i @clerk/clerk-sdk-node@4`). Some changes required for Core 2 SDKs can be applied incrementally to the v5 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.
+
+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
+
+Whenever you feel ready, go ahead and install the latest 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 version.
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+    ```bash filename="terminal"
+    npm install @clerk/clerk-sdk-node
+    ```
+
+    ```bash filename="terminal"
+    yarn add @clerk/clerk-sdk-node
+    ```
+
+    ```bash filename="terminal"
+    pnpm add @clerk/clerk-sdk-node
+    ```
+
+</CodeBlockTabs>
+
+## CLI upgrade helper
+
+Clerk now provides a `@clerk/upgrade` CLI tool that you can use to ease the upgrade process. The tool will scan your codebase and produce a list of changes you'll need to apply to your project. It should catch the vast majority of the changes needed for a successful upgrade to any SDK including Core 2. This can save you a lot of time reading through changes that don't apply to 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
+
+### `cjs/instance` and `esm/instance` imports no longer needed
+
+If you are using either of these import paths, they are no longer necessary and you can import directly from the top level `@clerk/express` path.
+
+```diff
+- import { ... } from "@clerk/clerk-sdk-node/esm/instance";
+- import { ... } from "@clerk/clerk-sdk-node/cjs/instance";
++ import { ... } from "@clerk/clerk-sdk-node";
+```
+
+### Clerk client setters removed in favor of `createClerkClient` options
+
+The following setter methods have been removed in the lastest version. If you were using any of these functions, their functionality can be replaced by instead passing the correponding option to `createClerkClient`.
+
+- `setClerkApiVersion`
+- `setClerkHttpOptions`
+- `setClerkServerApiUrl`
+- `setClerkApiKey`
+
+Code example:
+
+```diff
+  import {
+     clerkClient,
+-    setClerkApiKey,
+-    setClerkApiVersion,
+-    setClerkHttpOptions,
+-    setClerkServerApiUrl
+} from "@clerk/clerk-sdk-node"
+
+- setClerkApiKey("...")
+- setClerkApiVersion("...")
+- setClerkHttpOptions("...")
+- setClerkServerApiUrl("...")
+
+  const clerkClient = createClerkClient({
++     secretKey: "..."
++     apiVersion: "..."
++     httpOptions: "..."
++     serverApiUrl: "..."
+  })
+
+  await clerkClient.users.getUser(userId);
+```
+
+### 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.
+
+### 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>OrganizationMembershipPublicUserData.profileImageUrl</code> -&gt; <code>.imageUrl</code>", "<code>ExternalAccount.picture</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 `profileImageUrl` property of any `OrganizationMembershipPublicUserData` 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>
+</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>CLERK_API_KEY</code> replaced by <code>CLERK_SECRET_KEY</code>", "<code>CLERK_FRONTEND_API</code> replaced by <code>CLERK_PUBLISHABLE_KEY</code>", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to ClerkExpressRequireAuth", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to ClerkExpressWithAuth", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to createClerkClient", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to createClerkExpressRequireAuth", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to createClerkExpressWithAuth", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to createClerkClient", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to createClerkExpressRequireAuth", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to ClerkExpressRequireAuth", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to createClerkExpressWithAuth", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to ClerkExpressWithAuth"]}>
+  <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 `CLERK_API_KEY` environment variable was renamed to `CLERK_SECRET_KEY`. You can visit your [Clerk dashboard](https://dashboard.clerk.com/last-active?path=api-keys) to copy/paste the new keys after choosing your framework. Make sure to update this in all environments (e.g. dev, staging, production).
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `CLERK_FRONTEND_API` environment variable was renamed to `CLERK_PUBLISHABLE_KEY`. You can visit your [Clerk dashboard](https://dashboard.clerk.com/last-active?path=api-keys) to copy/paste the new keys after choosing your framework. Make sure to update this in all environments (e.g. dev, staging, production). **Note:** The values are different, so this is not just a key replacement. [More information](/docs/deployments/overview#api-keys-and-environment-variables).
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `ClerkExpressRequireAuth` must be changed to `secretKey`.
+    
+    ```diff
+    import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';
+    
+    - ClerkExpressRequireAuth({ apiKey: '...' });
+    + ClerkExpressRequireAuth({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `ClerkExpressWithAuth` must be changed to `secretKey`.
+    
+    ```diff
+    import { ClerkExpressWithAuth } from '@clerk/clerk-sdk-node';
+    
+    - ClerkExpressWithAuth({ apiKey: '...' });
+    + ClerkExpressWithAuth({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `createClerkClient` must be changed to `secretKey`.
+    
+    ```diff
+    import { createClerkClient } from '@clerk/clerk-sdk-node';
+    
+    - createClerkClient({ apiKey: '...' });
+    + createClerkClient({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `createClerkExpressRequireAuth` must be changed to `secretKey`.
+    
+    ```diff
+    import { createClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';
+    
+    - createClerkExpressRequireAuth({ apiKey: '...' });
+    + createClerkExpressRequireAuth({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `createClerkExpressWithAuth` must be changed to `secretKey`.
+    
+    ```diff
+    import { createClerkExpressWithAuth } from '@clerk/clerk-sdk-node';
+    
+    - createClerkExpressWithAuth({ apiKey: '...' });
+    + createClerkExpressWithAuth({ secretKey: '...' });
+    ```
+  </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.
+    
+    ```diff
+    import { createClerkClient } from '@clerk/clerk-sdk-node';
+    
+    - createClerkClient({ frontendApi: '...' });
+    + createClerkClient({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` argument passed to `createClerkExpressRequireAuth` 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.
+    
+    ```diff
+    import { createClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';
+    
+    - createClerkExpressRequireAuth({ frontendApi: '...' });
+    + createClerkExpressRequireAuth({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` argument passed to `ClerkExpressRequireAuth` 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.
+    
+    ```diff
+    import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';
+    
+    - ClerkExpressRequireAuth({ frontendApi: '...' });
+    + ClerkExpressRequireAuth({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` argument passed to `createClerkExpressWithAuth` 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.
+    
+    ```diff
+    import { createClerkExpressWithAuth } from '@clerk/clerk-sdk-node';
+    
+    - createClerkExpressWithAuth({ frontendApi: '...' });
+    + createClerkExpressWithAuth({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` argument passed to `ClerkExpressWithAuth` 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.
+    
+    ```diff
+    import { ClerkExpressWithAuth } from '@clerk/clerk-sdk-node';
+    
+    - ClerkExpressWithAuth({ frontendApi: '...' });
+    + ClerkExpressWithAuth({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+</Accordion>
+
+#### Other Breaking changes
+
+<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", "<code>Users.getOrganizationMembershipList</code> return signature changed", "<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>Invitations.getInvitationList</code> return signature changed", "<code>Sessions.getSessionList</code> return signature changed", "<code>Users.getUserList</code> return signature changed", "<code>AllowlistIdentifiers.getAllowlistIdentifierList</code> return signature changed", "<code>Clients.getClientList</code> return signature changed", "<code>RedirectUrls.getRedirectUrlList</code> return signature changed", "<code>Users.getUserOauthAccessToken</code> return signature changed", "<code>API_URL</code> value has changed", "<code>LegacyAuthObject</code> type -&gt; <code>AuthObject</code>", "<code>Clerk</code> -&gt; <code>{ createClerkClient }</code>", "<code>createClerkExpressRequireAuth</code> requires publishable key", "<code>createClerkExpressWithAuth</code> requires publishable key"]}>
+  <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>
+  <AccordionPanel>    
+    The response payload of `Users.getOrganizationMembershipList` was changed as part of the core 2 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>
+  <AccordionPanel>    
+    The response payload of `Users.getOrganizationInvitationList` was changed as part of the core 2 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 core 2 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 `Invitations.getInvitationList` was changed as part of the core 2 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.invitations.getInvitationList()
+    + const { data, totalCount } = await clerkClient.invitations.getInvitationList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `Sessions.getSessionList` was changed as part of the core 2 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.sessions.getSessionList()
+    + const { data, totalCount } = await clerkClient.sessions.getSessionList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `Users.getUserList` was changed as part of the core 2 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.getUserList()
+    + const { data, totalCount } = await clerkClient.users.getUserList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `AllowlistIdentifiers.getAllowlistIdentifierList` was changed as part of the core 2 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.allowlistIdentifiers.getAllowlistIdentifierList()
+    + const { data, totalCount } = await clerkClient.allowlistIdentifiers.getAllowlistIdentifierList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `Clients.getClientList` was changed as part of the core 2 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.clients.getClientList()
+    + const { data, totalCount } = await clerkClient.allowlistIdentifiers.getClientList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `RedirectUrls.getRedirectUrlList` was changed as part of the core 2 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.redirectUrls.getRedirectUrlList()
+    + const { data, totalCount } = await clerkClient.redirectUrls.getRedirectUrlList()
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The response payload of `Users.getUserOauthAccessToken` was changed as part of the core 2 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.getUserOauthAccessToken()
+    + const { data, totalCount } = await clerkClient.users.getUserOauthAccessToken()
+    ```
+  </AccordionPanel>
+  <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>    
+    We changed the values that our middleware adds to the `request` object after running. Previously it returned a `LegacyAuthObject` type, and now it returns an `AuthObject` type, the difference between the two types is as such:
+    
+    ```diff
+    - type LegacyAuthObject = {
+    + type AuthObject = {
+        sessionId: string | null;
+        actor: ActClaim | undefined | null;
+        userId: string | null;
+        getToken: ServerGetToken | null;
+        debug: AuthObjectDebug | null;
+    -   claims: JwtPayload | null;
+    +   sessionClaims: JwtPayload | null;
+    +   orgId: string | undefined | null;
+    +   orgRole: OrganizationCustomRoleKey | undefined | null;
+    +   orgSlug: string | undefined | null;
+    +   orgPermissions: OrganizationCustomPermissionKey[] | undefined | null;
+    +   has: CheckAuthorizationWithCustomPermissions | null;
+      }
+    ```
+    
+    If you were using the `claims` key on the request after running middleware, you will need to instead use `sessionClaims`. Additionally, if you were using the `LooseAuthProp` or `StrictAuthProp` exported types anywhere, note that these have been adjusted to fit the shape of the new middleware response typing.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `Clerk` default import has changed to `createClerkClient` and been moved to a named import rather than default. 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 Clerk from "@clerk/clerk-sdk-node"
+    + import { createClerkClient } from "@clerk/clerk-sdk-node"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `createClerkExpressRequireAuth` method now requires a clerk public key in order to work correctly. It can be passed in as a parameter directly, or picked up via environment variable. An error will be thrown now if there's no public key provided, this was not previously the case.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `createClerkExpressWithAuth` method now requires a clerk public key in order to work correctly. It can be passed in as a parameter directly, or picked up via environment variable. An error will be thrown now if there's no public key provided, this was not previously the case.
+  </AccordionPanel>
+</Accordion>
+
+
+

package/dist/guide-generators/core-2/overview/__output.mdx

@@ -0,0 +1,33 @@
+---
+title: "Upgrading to Clerk Core 2"
+description: "Learn how to upgrade to the latest version of Clerk's SDKs"
+---
+
+{/* WARNING: This is a generated file and should not be edited directly. To update its contents, see the "upgrade" package in the clerk/javascript repo. */}
+
+# Upgrading to Clerk Core 2
+
+In Febrary 2024, [we updated](https://clerk.com/changelog/2024-01-16) Clerk's SDKs to include Core 2. This new core includes:
+
+- 💅 Redesigned and improved component UIs.
+- 🔪 The 401 & "flash of white page" that was visible sometimes when syncing auth state was eliminated.
+- 🧹 A large number of smaller housekeeping changes, bugfixes, and improvements.
+- 📊 [Telemetry](/docs/telemetry) to allow us to better determine feature usage and priority (easy opt-out if you don't like this)
+
+## SDK Guides
+
+Core 2 brings both UI changes and breaking code changes, so each SDK has been updated to a new major version.
+We expect upgrades to take less than 30 minutes, and are providing a CLI tool to assist with the process. Please select your SDK below to get started:
+
+- [Next.js](/nextjs)
+- [Remix](/remix)
+- [Expo](/expo)
+- [Node](/node)
+- [Fastify](/fastify)
+- [React](/react)
+- [Backend](/backend)
+- [JS](/js)
+- [Chrome Extension](/chrome-extension)
+
+Note that the `Gastsby`, `Go`, and `Ruby` SDKs do not yet have a core 2 release ready - if you are using any of these SDKs there is nothing actionable right now.
+

package/dist/guide-generators/core-2/overview/intro.mdx

@@ -22,4 +22,4 @@ We expect upgrades to take less than 30 minutes, and are providing a CLI tool to
 - [JS](/js)
 - [Chrome Extension](/chrome-extension)
 
-Note that the `Gastsby`, `Go`, and `Ruby` SDKs do not yet have a beta release ready - if you are using any of these SDKs there is nothing actionable right now.
+Note that the `Gastsby`, `Go`, and `Ruby` SDKs do not yet have a core 2 release ready - if you are using any of these SDKs there is nothing actionable right now.