Upgrading @clerk/nextjs to Core 2

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 (with authMiddleware()):

middleware.ts
import { authMiddleware } from "@clerk/nextjs"
 
export default authMiddleware({
  publicRoutes: ["/", "/contact"],
})
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}

After (with clerkMiddleware()):

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)(.*)"],
}

You can protect a single route by using the createRouteMatcher() helper.

Before (with authMiddleware()):

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 (with clerkMiddleware()):

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)(.*)"],
}

You can call other Middlewares inside clerkMiddleware(), giving you more direct control over what is called where. An example would be next-intl(opens in a new tab) to add internationalization to your app.

Before (with authMiddleware()):

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 (with clerkMiddleware()):

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)(.*)"],
}

Previously these exports have been exported both from @clerk/nextjs and @clerk/nextjs/server. As of v5, they are only exported from the latter.

  import {
    auth,
    currentUser,
    authMiddleware,
    buildClerkProps,
    verifyToken,
    verifyJwt,
    decodeJwt,
    signJwt,
    constants,
    redirect,
    createAuthenticateRequest,
    createIsomorphicRequest,
- } from "@clerk/nextjs"
+ } from "@clerk/nextjs/server"

Exports related to errors are now under @clerk/nextjs/errors.

  import {
    isClerkAPIResponseError,
    isEmailLinkError,
    isKnownError,
    isMetamaskError,
    EmailLinkErrorCode,
- } from "@clerk/nextjs"
+ } from "@clerk/nextjs/errors"

The @clerk/nextjs import will work with both the App and Pages Router.

- 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.

The top-level exports support SSR by default now.

- import { } from "@clerk/nextjs/ssr"
+ import { } from "@clerk/nextjs"

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.

  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"

The logoUrl property of any Organization object(opens in a new tab) has been changed to imageUrl.

The profileImageUrl property of any User object has been changed to imageUrl.

The avatarUrl property of any ExternalAcccount object(opens in a new tab) has been changed to imageUrl.

The profileImageUrl property of any OrganizationMembershipPublicUserData object has been changed to imageUrl.

If you are updating a user's password via the User.update method(opens in a new tab), it must be changed to User.updatePassword(opens in a new tab) 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:

- user.update({ password: 'foo' });
 
+ user.updatePassword({
+   currentPassword: 'bar',
+   newPassword: 'foo',
+   signOutOfOtherSessions: true,
+ });

The CLERK_API_KEY environment variable was renamed to CLERK_SECRET_KEY. You can visit your Clerk dashboard(opens in a new tab) to copy/paste the new keys after choosing your framework. Make sure to update this in all environments (e.g. dev, staging, production).

The CLERK_FRONTEND_API environment variable was renamed to CLERK_PUBLISHABLE_KEY. You can visit your Clerk dashboard(opens in a new tab) 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.

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.

The apiKey argument passed to authMiddleware must be changed to secretKey.

import { authMiddleware } from '@clerk/nextjs';
 
- authMiddleware({ apiKey: '...' });
+ authMiddleware({ secretKey: '...' });

The frontendApi argument passed to authMiddleware must be changed to publishableKey

import { authMiddleware } from "@clerk/nextjs/server"
 
- authMiddleware({ frontendApi: '...' })
+ authMiddleware({ publishableKey: '...' })

The apiKey argument passed to createClerkClient must be changed to secretKey.

import { createClerkClient } from '@clerk/nextjs/server';
 
- createClerkClient({ apiKey: '...' });
+ createClerkClient({ secretKey: '...' });

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.

import { createClerkClient } from '@clerk/nextjs/server';
 
- createClerkClient({ frontendApi: '...' });
+ createClerkClient({ publishableKey: '...' });

The apiKey argument passed to getAuth must be changed to secretKey.

- getAuth({ apiKey: '...' })
+ getAuth({ secretKey: '...' })

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(opens in a new tab) 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.

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 App Router support is stable.

Make this change carefully as some behavior may have changed between our beta and stable releases. You can refer to our documentation(opens in a new tab) and/or approuter example(opens in a new tab) for up-to-date usage.

The @clerk/nextjs import will work with both App Router and Pages Router.

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.

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.

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.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the CLERK_API_URL environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the CLERK_API_VERSION environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_JS_URL environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_JS_VERSION environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_DOMAIN environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_IS_SATELLITE environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_PROXY_URL environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY environment variable.

This deprecated constant has been removed as an export from @clerk/nextjs. Instead, set and use the CLERK_SECRET_KEY environment variable.

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.

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.

The import subpath @clerk/nextjs/api has been removed. This includes the following imports:

// 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.

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:

- import { MultiSessionAppSupport } from "@clerk/nextjs"
+ import { MultiSessionAppSupport } from "@clerk/nextjs/internal"

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.

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:

  const { data } = await organization.getRoles({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await organization.getMemberships({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await organization.getDomains({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await organization.getInvitations({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await organization.getMembershipRequests({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await user.getOrganizationInvitations({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await user.getOrganizationSuggestions({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

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:

  const { data } = await user.getOrganizationMemberships({
-   limit: 10,
+   pageSize: 10,
-   offset: 10,
+   initialPage: 2,
  })

The response payload of Users.getOrganizationInvitationList was changed as part of the v5 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getOrganizationInvitationList()
+ const { data, totalCount } = await clerkClient.users.getOrganizationInvitationList()

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:

  const data = await clerkClient.organizations.getOrganizationInvitationList({
    organizationId: "...",
  })
 
- data.forEach(() => {})
+ data.data.forEach(() => {})

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:

  const { user } = useUser()
  const membershipList = user.getOrganizationMembershipList()
 
- membershipList.forEach(() => {})
+ membershipList.data.forEach(() => {})

The response payload of Users.getOrganizationList was changed as part of the v5 release. Rather than directly returning data, the return signature is now { data, totalCount }. Since backend API responses are paginated, the totalCount property is helpful in determining the total number of items in the response easily, and this change in the backend SDK aligns the response shape with what the backend API returns directly.

Here's an example of how the response shape would change with this modification:

- const data = await clerkClient.users.getOrganizationList()
+ const { data, totalCount } = await clerkClient.users.getOrganizationList()

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:

  const { organization } = useOrganization()
  const orgList = organization.getOrganizationList()
 
- orgList.forEach(() => {})
+ orgList.data.forEach(() => {})

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 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:

- 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:

await setActive({
  session: 'sessionID',
  organization: 'orgID',
  beforeEmit: () => void
})
 
await setActive({
  session: sessionObj,
  organization: orgObj,
  beforeEmit: () => void
})

Passing a string as an argument to Organization.create is no longer possible - instead, pass an object with the name property.

- Organization.create('...');
+ Organization.create({ name: '...' });

The Organization.getPendingInvitations() method has been removed. You can use Organization.getInvitations instead.

- Organization.getPendingInvitations();
+ Organization.getInvitations({ status: 'pending' });

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.

Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.

Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects functionality.

Across Clerk's documentation and codebases the term "magic link" was changed to "email link" as it more accurately reflects the functionality.

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:

- import { isMetamaskError } from "@clerk/react"
+ import { isMetamaskError } from "@clerk/react/errors"

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(opens in a new tab). An example of how to do so is below:

export const WithSession = ({ children }) => {
  const session = useSession();
  if (typeof children !== 'function') throw new Error();
 
  return {children(session)};
};

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(opens in a new tab). An example of how to do so is below:

export const WithClerk = ({ children }) => {
  const clerk = useClerk();
  if (typeof children !== 'function') throw new Error();
 
  return {children(clerk)};
};

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(opens in a new tab). An example of how to do so is below:

export const WithUser = ({ children }) => {
  const user = useUser();
  if (typeof children !== 'function') throw new Error();
 
  return {children(user)};
};

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(opens in a new tab). An example of how to do so is below:

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;
}

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(opens in a new tab). An example of how to do so is below:

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;
}

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(opens in a new tab). An example of how to do so is below:

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;
}

The signOutCallback prop on the <SignOutButton /> component(opens in a new tab) has been removed. Instead, you can use the redirectUrl prop. Example below:

  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>
    )
  }