@clerk/upgrade 1.0.2 → 1.0.3

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

@@ -0,0 +1,1169 @@
+---
+title: "Upgrading Next.js to Core 2"
+description: "Learn how to upgrade Clerk's Next.js SDK to the latest 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/nextjs` to Core 2
+
+Core 2 is included in the Next.js SDK starting with version 5.0.0. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, a substantially improved middleware import, 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 Next.js project to use `@clerk/nextjs` 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/nextjs@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 React**
+
+All react-dependent Clerk SDKs now require you to use React 18 or higher. You can update your project by installing the latest version of `react` and `react-dom`.
+
+<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
+    ```bash filename="terminal"
+    npm install react@latest react-dom@latest
+    ```
+
+    ```bash filename="terminal"
+    yarn add react@latest react-dom@latest
+    ```
+
+    ```bash filename="terminal"
+    pnpm add react@latest react-dom@latest
+    ```
+
+</CodeBlockTabs>
+
+If you are upgrading from React 17 or lower, make sure to [learn about how to upgrade your React version to 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide) as well.
+
+**Updating Next.js**
+
+`@clerk/nextjs` now requires you to use Next.js version `13.0.4` or later. Check out Next's upgrade guides for more guidance if you have not yet upgraded to Next.js 13:
+
+- [Upgrading from 12 to 13](https://nextjs.org/docs/pages/building-your-application/upgrading/version-13)
+- [Upgrading from 13 to 14](https://nextjs.org/docs/app/building-your-application/upgrading/version-14)
+
+## 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/nextjs
+    ```
+
+    ```bash filename="terminal"
+    yarn add @clerk/nextjs
+    ```
+
+    ```bash filename="terminal"
+    pnpm add @clerk/nextjs
+    ```
+
+</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
+
+### Component design adjustments
+
+The new version ships with improved design and UX across all of Clerk's [UI components](/docs/components/overview). If you have used the [`appearance` prop](/docs/components/customization/overview) or tokens for a [custom theme](/docs/components/customization/overview#create-a-custom-theme), you will likely need to make some adjustments to ensure your styling is still looking great. If you're using the [localization prop](/docs/components/customization/localization) you will likely need to make adjustments to account for added or removed localization keys.
+
+[More detail on these changes &raquo;](component-redesign)
+
+### New Middleware architecture
+
+User and customer feedback about `authMiddleware()` has been clear in that Middleware logic was a often friction point. As such, in v5 you will find a completely new Middleware helper called [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware) that should alleviate the issues folks had with `authMiddleware()`.
+
+The primary change from the previous `authMiddleware()` is that `clerkMiddleware()` does not protect any routes by default, instead requiring the developer to add routes they would like to be protected by auth. This is a substantial contrast to the previous `authMiddleware()`, which protected all routes by default, requiring the developer to add exceptions. The API was also substantially simplified, and it has become easier to combine with other Middleware helpers smoothly as well.
+
+Here's an example that demonstrates route protection based on both authentication and authorization:
+
+```ts filename="middleware.ts"
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isDashboardRoute = createRouteMatcher(['/dashboard(.*)']);
+const isAdminRoute = createRouteMatcher(['/admin(.*)']);
+
+export default clerkMiddleware((auth, req) => {
+  // Restrict admin route to users with specific role
+  if (isAdminRoute(req)) auth().protect({ role: 'org:admin' });
+
+  // Restrict dashboard routes to logged in users
+  if (isDashboardRoute(req)) auth().protect();
+});
+
+export const config = {
+  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)'],
+};
+```
+
+A couple things to note here:
+
+- The `createRouteMatcher` helper makes it easy to define route groups that you can leverage inside the Middleware function and check in whichever order you'd like. Note that it can take an array of routes as well.
+- With `clerkMiddleware`, you're defining the routes you want **to be protected**, rather than the routes you don't want to be protected.
+- The [`auth().protect()`](https://clerk.com/docs/references/nextjs/auth#protect) helper is utilized heavily here, check out its docs for more info.
+
+See the [`clerkMiddleware()`](/docs/references/nextjs/clerk-middleware) docs for more information and detailed usage examples.
+
+#### Migrating to `clerkMiddleware()`
+
+Clerk strongly recommends migrating to the new `clerkMiddleware()` for an improved DX and access to all present and upcoming features, but also want to note that `authMiddleware()`, while deprecated, will continue to work in v5 and will not be removed until the next major version, so you do not _need_ to make any changes to your Middleware setup this version.
+
+The most basic migration will be updating the import and changing out the default export, then mirroring the previous behavior of protecting all routes as such:
+
+```diff
+- import { authMiddleware } from "@clerk/nextjs"
++ import { clerkMiddleware } from '@clerk/nextjs/server'
+
+- export default authMiddleware()
++ export default clerkMiddleware((auth) => auth().protect())
+
+  export const config = {
+    matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
+  }
+```
+
+Of course, in most cases you'll have a more complicated setup than this. You can find some examples below for how to migrate a few common use cases. Be sure to review the [`clerkMiddleware()` documentation](/docs/references/nextjs/clerk-middleware) if your specific use case is not mentioned.
+
+<Accordion titles={["Protecting all routes except one or more public paths", "Protecting a single route path", "Combining with other Middlewares (like i18n)", "Using the redirectToSignIn method"]} heading="h4">
+  <AccordionPanel>
+    By default, `clerkMiddleware()` treats all pages as public unless explicitly protected. If you prefer for it to operate the other way around (all pages are protected unless explicitly made public), you can reverse the middleware logic in this way:
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware } from "@clerk/nextjs"
+
+    export default authMiddleware({
+      publicRoutes: ["/", "/contact"],
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import {
+      clerkMiddleware,
+      createRouteMatcher
+    } from "@clerk/nextjs/server"
+
+    const isPublicRoute = createRouteMatcher(["/", "/contact"])
+
+    export default clerkMiddleware((auth, req) => {
+      if (isPublicRoute(req)) return // if it's a public route, do nothing
+      auth().protect() // for any other route, require auth
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    An example can be seen below of code that ensures that all routes are public except everything under `/dashboard`.
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware } from "@clerk/nextjs"
+
+    export default authMiddleware({
+      publicRoutes: (req) => !req.url.includes("/dashboard"),
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import {
+      clerkMiddleware,
+      createRouteMatcher
+    } from "@clerk/nextjs/server"
+
+    const isDashboardRoute = createRouteMatcher(["/dashboard(.*)"])
+
+    export default clerkMiddleware((auth, request) => {
+      if (isDashboardRoute(request)) auth().protect()
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    You can call other Middlewares inside `clerkMiddleware()`, giving you more direct control over what is called where. An example would be [next-intl](https://next-intl-docs.vercel.app/) to add internationalization to your app.
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware } from "@clerk/nextjs"
+    import createMiddleware from "next-intl/middleware"
+
+    const intlMiddleware = createMiddleware({
+      locales: ["en", "de"],
+      defaultLocale: "en",
+    })
+
+    export default authMiddleware({
+      beforeAuth: (req) => {
+        return intlMiddleware(req);
+      },
+      publicRoutes: ["((?!^/dashboard/).*)"],
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import {
+      clerkMiddleware,
+      createRouteMatcher
+    } from "@clerk/nextjs/server"
+    import createMiddleware from "next-intl/middleware"
+
+    const intlMiddleware = createMiddleware({
+      locales: ["en", "de"],
+      defaultLocale: "en",
+    })
+
+    const isDashboardRoute = createRouteMatcher(["/dashboard(.*)"])
+
+    export default clerkMiddleware((auth, request) => {
+      if (isDashboardRoute(request)) auth().protect()
+
+      return intlMiddleware(request)
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    You can now access `redirectToSignIn` from the `auth()` object, rather than importing at the top level.
+
+    Before:
+
+    ```ts filename="middleware.ts"
+    import { authMiddleware, redirectToSignIn } from "@clerk/nextjs"
+
+    export default authMiddleware({
+      if (someCondition) redirectToSignIn()
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+    After:
+
+    ```ts filename="middleware.ts"
+    import { clerkMiddleware } from "@clerk/nextjs/server"
+
+    export default clerkMiddleware((auth, req) => {
+      if (someCondition) auth().redirectToSignIn()
+    })
+
+    export const config = {
+      matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
+    }
+    ```
+
+  </AccordionPanel>
+</Accordion>
+
+### Changes to top-level exports
+
+As part of this release, some of the top-level exports of `@clerk/nextjs` have been changed in order to improve bundle size and tree-shaking efficiency. These changes have resulted in a ~75% reduction in build size for middleware bundles. However, you will likely need to make some changes to import paths as a result.
+
+<Callout type='info'>
+  Use [the CLI tool](#cli-upgrade-helper) to automatically find occurences of imports that need to be changed.
+</Callout>
+
+<Accordion titles={["@clerk/nextjs/server", "@clerk/nextjs/errors", "@clerk/nextjs/app-beta", "@clerk/nextjs/ssr", "@clerk/nextjs/edge-middleware", "@clerk/nextjs/edge-middlewarefiles", "@clerk/nextjs/api"]}>
+  <AccordionPanel>
+    Previously these exports have been exported both from `@clerk/nextjs` and `@clerk/nextjs/server`. As of v5 they are only exported from the latter. Going forward, the expectation can be that any imports that are intended to run within react on the client side, will come from `@clerk/nextjs` and imports that are intended to run on the server, will come from `@clerk/nextjs/server`.
+
+    ```diff
+      import {
+        auth,
+        currentUser,
+        authMiddleware,
+        buildClerkProps,
+        verifyToken,
+        verifyJwt,
+        decodeJwt,
+        signJwt,
+        constants,
+        redirect,
+        createAuthenticateRequest,
+        createIsomorphicRequest,
+    - } from "@clerk/nextjs"
+    + } from "@clerk/nextjs/server"
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    Exports related to errors are now under `@clerk/nextjs/errors`.
+
+    ```diff
+      import {
+        isClerkAPIResponseError,
+        isEmailLinkError,
+        isKnownError,
+        isMetamaskError,
+        EmailLinkErrorCode,
+    - } from "@clerk/nextjs"
+    + } from "@clerk/nextjs/errors"
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    The `@clerk/nextjs` import will work with both the app and pages router.
+
+    ```diff
+    - import { } from "@clerk/nextjs/app-beta"
+    + import { } from "@clerk/nextjs"
+    ```
+
+    Some behavior may have changed between Clerk's beta and the stable release. Please check on your end if behavior stayed the same.
+
+  </AccordionPanel>
+  <AccordionPanel>
+    The top-level exports support SSR by default now.
+
+    ```diff
+    - import { } from "@clerk/nextjs/ssr"
+    + import { } from "@clerk/nextjs"
+    ```
+
+  </AccordionPanel>
+  <AccordionPanel>
+    ```diff
+    - import { } from "@clerk/nextjs/edge-middleware"
+    + import { } from "@clerk/nextjs"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>
+    ```diff
+    - import { } from "@clerk/nextjs/edge-middlewarefiles"
+    + import { } from "@clerk/nextjs"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>
+    The `@clerk/nextjs/api` subpath was removed completely. It re-exported helpers from `@clerk/clerk-sdk-node` and its types. If you relied on these, import from `@clerk/clerk-sdk-node` directly instead.
+
+    ```diff
+      import type {
+        ClerkMiddleware,
+        ClerkMiddlewareOptions,
+        LooseAuthProp,
+        RequireAuthProp,
+        StrictAuthProp,
+        WithAuthProp
+    - } from "@clerk/nextjs/api"
+    + } from "@clerk/clerk-sdk-node"
+
+    - import { requireAuth, withAuth } from "@clerk/nextjs/api"
+    + import { requireAuth, withAuth } from "@clerk/clerk-sdk-node"
+    ```
+
+  </AccordionPanel>
+</Accordion>
+
+### After sign up/in/out default value change
+
+Defining redirect URLs for after sign up, in, and/or out via the Clerk dashboard has been removed in Core 2. In your Clerk dashboard, under "paths", there is a section called "Component paths", where URLs could be defined that had a deprecation warning. In Core 2, this functionality has been removed, and specifying redirect paths via the dashboard will no longer work. If you need to pass a redirect URL for after sign in/up/out, there are [a few different ways this can be done](https://clerk.com/docs/account-portal/custom-redirects), from environment variables to middleware to supplying them directly to the relevant components.
+
+As part of this change, the default URL for each of these props has been set to `/`, so if you are passing `/` explicitly to any one of the above props, that line is no longer necessary and can be removed.
+
+```diff
+- <UserButton afterSignOutUrl='/' />
++ <UserButton />
+```
+
+### `afterSignXUrl` changes
+
+Some changes are being made to the way that "after sign up/in url"s and redirect url props are handled as part of this new version, in order to make behavior more clear and predictable.
+
+> We will refer to these urls as `afterSignXUrl` where `X` could be `Up` or `In` depending on the context.
+
+Previously, setting `afterSignInUrl` or `afterSignOutUrl` would only actually redirect some of the time. If the user clicks on any form of link that takes them to a sign up/in page, Clerk automatically sets `redirect_url` in the querystring such that after the sign up or in, the user is returned back to the page they were on before. This is a common pattern for sign up/in flows, as it leads to the least interruption of the user's navigation through your app. When a `redirect_url` is present, any value passed to `afterSignInUrl` or `afterSignUpUrl` is ignored. However, if the user navigates directly to a sign up/in page, there’s no redirect url in the querystring and in this case the `afterSignInUrl` or `afterSignOutUrl` would take effect. This behavior was not intuitive and didn't give a way to force a redirect after sign up/in, so the behavior is changing to address both of these issues.
+
+All `afterSignXUrl` props and `CLERK_AFTER_SIGN_X_URL` environment variables have been removed, and should be replaced by one of the following options:
+
+- `signXForceRedirectUrl` / `CLERK_SIGN_X_FORCE_REDIRECT_URL` - if set, Clerk will always redirect to provided URL, regardless of what page the user was on before. Use this option with caution, as it will interrupt the user’s flow by taking them away from the page they were on before.
+- `signXFallbackRedirectUrl` / `CLERK_SIGN_UP_FALLBACK_REDIRECT_URL` - if set, this will mirror the previous behavior, only redirecting to the provided URL if there is no `redirect_url` in the querystring.
+
+If neither value is set, Clerk will redirect to the `redirect_url` if present, otherwise it will redirect to `/`. If you'd like to retain the current behavior of your app without any changes, you can switch `afterSignXUrl` with `signXFallbackRedirectUrl` as such:
+
+```diff
+- <SignIn afterSignInUrl='/foo' />
++ <SignIn signInFallbackRedirectUrl='/foo' />
+```
+
+### 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.
+
+### Path routing is now the default
+
+On components like [`<SignIn />`](/docs/components/authentication/sign-in) you can define the props `routing` and `path`. `routing` can be set to `'hash' | 'path' | 'virtual'` and describes the routing strategy that should be used. `path` defines where the component is mounted when `routing="path"` is used.
+
+In the latest version, the **default** `routing` strategy has become `'path'`. Unless you change the `routing` prop, you'll need to define the `path` prop. The affected components are:
+
+- `<SignIn />`
+- `<SignUp />`
+- `<UserProfile />`
+- `<CreateOrganization />`
+- `<OrganizationProfile />`
+
+Here's how you'd use the components going forward:
+
+```jsx
+<SignIn path="/sign-in" />
+<SignUp path="/sign-up" />
+<UserProfile path="/user-profile" />
+<CreateOrganization path="/create-org" />
+<OrganizationProfile path="/org-profile" />
+```
+
+If you don't define the `path` prop an error will be thrown. Of course, you can still use `routing="hash"` or `routing="virtual"`.
+
+```jsx
+<UserProfile routing="hash" />
+<OrganizationProfile routing="virtual" />
+```
+
+
+For the @clerk/nextjs SDK, you can set environment variables for the sign up/in URLs and avoid needing to explicitly pass the path to the `<SignIn />` and `<SignUp />` components.
+
+
+
+```env filename=".env.local"
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+```
+
+
+
+
+If you have defined both environment variables, you're able to use the `<SignIn />` and `<SignUp />` components without any props, as such:
+
+```jsx
+<SignIn />
+<SignUp />
+```
+
+
+
+### 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.avatarUrl</code> -&gt; <code>.imageUrl</code>", "<code>OrganizationMembershipPublicUserData.profileImageUrl</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 `avatarUrl` property of any [`ExternalAcccount` object](https://clerk.com/docs/references/javascript/external-account) has been changed to `imageUrl`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `profileImageUrl` property of any `OrganizationMembershipPublicUserData` 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>CLERK_API_KEY</code> replaced by <code>CLERK_SECRET_KEY</code>", "<code>CLERK_FRONTEND_API</code> replaced by <code>CLERK_PUBLISHABLE_KEY</code>", "<code>CLERK_JS_VERSION</code> should be <code>NEXT_PUBLIC_CLERK_JS_VERSION</code>", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to <code>authMiddleware</code>", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to <code>authMiddleware</code>", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to <code>createClerkClient</code>", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as param to <code>createClerkClient</code>", "<code>apiKey</code> -&gt; <code>secretKey</code> as param to <code>getAuth</code>", "<code>frontendApi</code> -&gt; <code>publishableKey</code> as prop to <code>ClerkProvider</code>", "<code>@clerk/nextjs/app-beta</code> import removed", "<code>@clerk/nextjs/ssr</code> import removed", "<code>@clerk/nextjs/edge-middleware</code> import removed", "<code>@clerk/nextjs/edge-middlewarefiles</code> import removed", "<code>API_URL</code> constant removed", "<code>API_VERSION</code> constant removed", "<code>CLERK_JS_URL</code> constant removed", "<code>CLERK_JS_VERSION</code> constant removed", "<code>DOMAIN</code> constant removed", "<code>IS_SATELLITE</code> constant removed", "<code>PROXY_URL</code> constant removed", "<code>PUBLISHABLE_KEY</code> constant removed", "<code>SECRET_KEY</code> constant removed", "<code>SIGN_IN_URL</code> constant removed", "<code>SIGN_UP_URL</code> constant removed", "<code>@clerk/nextjs/api</code> import removed", "<code>MultiSessionAppSupport</code> import moved under <code>/internal</code>", "<code>NEXT_PUBLIC_CLERK_JS</code> should be <code>NEXT_PUBLIC_CLERK_JS_URL</code>"]}>
+  <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>    
+    If you are using `CLERK_JS_VERSION` as an environment variable, it should be changed to `NEXT_PUBLIC_CLERK_JS_VERSION` instead.
+    
+    This change brings our SDK up to date with the latest standards for next.js - that public environment variables should have the `NEXT_PUBLIC_` prefix. This env variable is not private, so it should get the public prefix.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `authMiddleware` must be changed to `secretKey`.
+    
+    ```diff
+    import { authMiddleware } from '@clerk/nextjs';
+    
+    - authMiddleware({ apiKey: '...' });
+    + authMiddleware({ secretKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` argument passed to `authMiddleware` must be changed to `publishableKey`
+    
+    ```diff
+    import { authMiddleware } from "@clerk/nextjs/server"
+    
+    - authMiddleware({ frontendApi: '...' })
+    + authMiddleware({ publishableKey: '...' })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `createClerkClient` must be changed to `secretKey`.
+    
+    ```diff
+    import { createClerkClient } from '@clerk/nextjs/server';
+    
+    - createClerkClient({ apiKey: '...' });
+    + createClerkClient({ 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/nextjs/server';
+    
+    - createClerkClient({ frontendApi: '...' });
+    + createClerkClient({ publishableKey: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `apiKey` argument passed to `getAuth` must be changed to `secretKey`.
+    
+    ```diff
+    - getAuth({ apiKey: '...' })
+    + getAuth({ secretKey: '...' })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `frontendApi` prop passed to `<ClerkProvider>` was renamed to `publishableKey`. **Note:** The values are different, so this is not just a key replacement. 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). [More information](/docs/deployments/overview#api-keys-and-environment-variables).
+  </AccordionPanel>
+  <AccordionPanel>    
+    If you are using the `@clerk/nextjs/app-beta` import anywhere, it should use `@clerk/nextjs` instead. The `app-beta` import has been removed as our approuter support is stable, if there are any places you’re using it you can remove.
+    
+    Make this change carefully as some behavior may have changed between our beta and stable releases. You can refer to [our documentation](https://clerk.com/docs/quickstarts/nextjs) and/or [approuter example](https://github.com/clerk/clerk-nextjs-app-quickstart) for up-to-date usage.
+    
+    The `@clerk/nextjs` import will work with both App Router and Pages Router.
+  </AccordionPanel>
+  <AccordionPanel>    
+    If you are importing from `@clerk/nextjs/ssr`, you can use `@clerk/nextjs` instead. Our top-level import supports SSR functionality by default now, so the subpath on the import is no longer needed. This import can be directly replaced without any other considerations.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated import has been replaced by `@clerk/nextjs`. Usage should now look as such: `import { authMiddleware } from @clerk/nextjs`. There may be changes in functionality between the two exports depending on how old the version used is, so upgrade with caution.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated import has been replaced by `@clerk/nextjs`. Usage should now look as such: `import { authMiddleware } from @clerk/nextjs`. There may be changes in functionality between the two exports depending on how old the version used is, so upgrade with caution.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `CLERK_API_URL` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `CLERK_API_VERSION` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_JS` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_JS_VERSION` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_DOMAIN` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_IS_SATELLITE` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_PROXY_URL` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `CLERK_SECRET_KEY` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_SIGN_IN_URL` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    This deprecated constant has been removed as an export from `@clerk/nextjs`. Instead, set and use the `NEXT_PUBLIC_CLERK_SIGN_UP_URL` environment variable.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The import subpath `@clerk/nextjs/api` has been removed. This includes the following imports:
+    
+    ```js
+    // These have been removed
+    import {
+      ClerkMiddleware,
+      ClerkMiddlewareOptions,
+      LooseAuthProp,
+      RequireAuthProp,
+      StrictAuthProp,
+      WithAuthProp,
+    } from '@clerk/nextjs/api';
+    ```
+    
+    If you still need to use any of these functions, they can be instead imported from `@clerk/clerk-sdk-node`.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `MultiSessionAppSupport` import path has changed from `@clerk/nextjs` to `@clerk/nextjs/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 { MultiSessionAppSupport } from "@clerk/nextjs"
+    + import { MultiSessionAppSupport } from "@clerk/nextjs/internal"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    If you are using `NEXT_PUBLIC_CLERK_JS` as an environment variable, it should be changed to `NEXT_PUBLIC_CLERK_JS_URL` instead. This variable was renamed for consistency across public APIs. Make sure to also check your production host configuration when changing environment variable values.
+  </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>setSession</code> -&gt; <code>setActive</code>", "<code>Organization.create(&#39;x&#39;)</code> -&gt; <code>Organization.create({ name: &#39;x&#39; })</code>", "<code>Organization.getPendingInvitations()</code> -&gt; <code>Organization.getInvitations({ status: &#39;pending&#39; })</code>", "<code>API_URL</code> value has changed", "<code>isMagicLinkError</code> -&gt; <code>isEmailLinkError</code>", "<code>useMagicLink</code> -&gt; <code>useEmailLink</code>", "<code>MagicLinkErrorCode</code> -&gt; <code>EmailLinkErrorCode</code>", "<code>isMetamaskError</code> import moved under <code>/errors</code>", "<code>WithSession</code> component removed", "<code>WithClerk</code> component removed", "<code>WithUser</code> component removed", "<code>withClerk</code> function removed", "<code>withSession</code> function removed", "<code>withUser</code> function removed", "Replace <code>signOutCallback</code> prop on <code>SignOutButton</code> with <code>redirectUrl</code>"]}>
+  <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>    
+    `setSession` should be replaced with `setActive`. The format of the parameters has changed slightly - `setActive` takes an object where `setSession` took params directly. The `setActive` function also can accept an `organization` param that is used to set the currently active organization. The return signature did not change. Read the [API documentation](/docs/references/javascript/clerk/session-methods#set-active) for more detail. This function should be expected to be returned from one of the following Clerk hooks: `useSessionList`, `useSignUp`, or `useSignIn`. Some migration examples:
+    
+    ```diff
+    - await setSession('sessionID', () => void)
+    + await setActive({ session: 'sessionID',  beforeEmit: () => void })
+    
+    - await setSession(sessionObj)
+    + await setActive({ session: sessionObj })
+    
+    - await setSession(sessionObj, () => void)
+    + await setActive({ session: sessionObj,  beforeEmit: () => void })
+    ```
+    
+    `setActive` also supports setting an active organization:
+    
+    ```js
+    await setActive({
+      session: 'sessionID',
+      organization: 'orgID',
+      beforeEmit: () => void
+    })
+    
+    await setActive({
+      session: sessionObj,
+      organization: orgObj,
+      beforeEmit: () => void
+    })
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    Passing a string as an argument to `Organization.create` is no longer possible - instead, pass an object with the `name` property.
+    
+    ```diff
+    - Organization.create('...');
+    + Organization.create({ name: '...' });
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `Organization.getPendingInvitations()` method has been removed. You can use `Organization.getInvitations` instead.
+    
+    ```diff
+    - Organization.getPendingInvitations();
+    + Organization.getInvitations({ status: 'pending' });
+    ```
+  </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>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `isMetamaskError` import path has changed from `@clerk/react` to `@clerk/react/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 { isMetamaskError } from "@clerk/react"
+    + import { isMetamaskError } from "@clerk/react/errors"
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `WithSession` higher order component has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's [custom hooks](https://clerk.com/docs/references/react/overview). An example of how to do so is below:
+    
+    ```js
+    export const WithSession = ({ children }) => {
+      const session = useSession();
+      if (typeof children !== 'function') throw new Error();
+    
+      return {children(session)};
+    };
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `WithClerk` higher order component has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's [custom hooks](https://clerk.com/docs/references/react/overview). An example of how to do so is below:
+    
+    ```js
+    export const WithClerk = ({ children }) => {
+      const clerk = useClerk();
+      if (typeof children !== 'function') throw new Error();
+    
+      return {children(clerk)};
+    };
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `WithUser` higher order component has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's [custom hooks](https://clerk.com/docs/references/react/overview). An example of how to do so is below:
+    
+    ```js
+    export const WithUser = ({ children }) => {
+      const user = useUser();
+      if (typeof children !== 'function') throw new Error();
+    
+      return {children(user)};
+    };
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `withClerk` higher order function has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's [custom hooks](https://clerk.com/docs/references/react/overview). An example of how to do so is below:
+    
+    ```js
+    function withClerk(Component, displayName) {
+      displayName = displayName || Component.displayName || Component.name || 'Component';
+      Component.displayName = displayName;
+      const HOC = props => {
+        const clerk = useIsomorphicClerkContext();
+    
+        if (!clerk.loaded) return null;
+    
+        return (
+          <Component
+            {...props}
+            clerk={clerk}
+          />
+        );
+      };
+    
+      HOC.displayName = `withClerk(${displayName})`;
+      return HOC;
+    }
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `withSession` higher order function has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's [custom hooks](https://clerk.com/docs/references/react/overview). An example of how to do so is below:
+    
+    ```js
+    function withSession(Component, displayName) {
+      displayName = displayName || Component.displayName || Component.name || 'Component';
+      Component.displayName = displayName;
+      const HOC = props => {
+        const session = useSessionContext();
+    
+        if (!session) return null;
+    
+        return (
+          <Component
+            {...props}
+            session={session}
+          />
+        );
+      };
+    
+      HOC.displayName = `withSession(${displayName})`;
+      return HOC;
+    }
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `withUser` higher order function has been removed. If you would still like to use this function in the way its implemented, it can be created quickly using Clerk's [custom hooks](https://clerk.com/docs/references/react/overview). An example of how to do so is below:
+    
+    ```js
+    function withUser(Component, displayName) {
+      displayName = displayName || Component.displayName || Component.name || 'Component';
+      Component.displayName = displayName;
+      const HOC = props => {
+        const clerk = useUserContext();
+    
+        if (!user) return null;
+    
+        return (
+          <Component
+            {...props}
+            user={user}
+          />
+        );
+      };
+    
+      HOC.displayName = `withUser(${displayName})`;
+      return HOC;
+    }
+    ```
+  </AccordionPanel>
+  <AccordionPanel>    
+    The `signOutCallback` prop on the [`<SignOutButton />` component](https://clerk.com/docs/components/unstyled/sign-out-button) has been removed. Instead, you can use the `redirectUrl` prop. Example below:
+    
+    ```diff
+      import { SignOutButton } from "@clerk/clerk-react";
+    
+      export const Signout = () => {
+        return (
+          <SignOutButton
+    -       signOutCallback={() => { window.location.href = "/your-path" }}
+    +       redirectUrl="/your-path"
+          >
+            <button>Sign Out</button>
+          </SignOutButton>
+        )
+      }
+    ```
+  </AccordionPanel>
+</Accordion>
+
+
+