Upgrading `@clerk/remix` to Core 2

Preparing to upgrade
Updating to Core 2
CLI upgrade helper
Breaking Changes

Core 2 is included in the Remix SDK starting with version 4. This new version ships with an improved design and UX for its built-in components, no "flash of white page" when authenticating, no more need to add a custom error boundary, 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 Remix project to use @clerk/remix v4. 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 upgrading, it's highly recommended that you update your Clerk SDKs to the latest Core 1 version (npm i @clerk/remix@3). Some changes required for Core 2 SDKs can be applied incrementally to the v4 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 minimum 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.

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.

npm

yarn

pnpm

bun

terminal

npm install react@latest react-dom@latest

terminal

yarn add react@latest react-dom@latest

terminal

pnpm add react@latest react-dom@latest

terminal

bun add react@latest react-dom@latest

If you are upgrading from React 17 or lower, make sure to learn about how to upgrade your React version to 18 as well.

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.

npm

yarn

pnpm

bun

terminal

npm install @clerk/remix

terminal

yarn add @clerk/remix

terminal

pnpm add @clerk/remix

terminal

bun add @clerk/remix

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:

npm

yarn

pnpm

bun

terminal

npx @clerk/upgrade --from=core-1

terminal

yarn dlx @clerk/upgrade --from=core-1

terminal

pnpm dlx @clerk/upgrade --from=core-1

terminal

bun dlx @clerk/upgrade --from=core-1

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

`ClerkErrorBoundary` removed

ClerkErrorBoundary is no longer needed for correct error handling in remix, so we have removed this function from the remix SDK, and it can be removed from your code as well. Example below:

  import { rootAuthLoader } from '@clerk/remix/ssr.server'
  import {
    ClerkApp,
-   ClerkErrorBoundary,
  } from '@clerk/remix'
  
  export const loader = (args: DataFunctionArgs) => {
    return rootAuthLoader(args)
  }
  
  export default ClerkApp(App)
  
- export const ErrorBoundary = ClerkErrorBoundary()

Component design adjustments

The new version ships with improved design and UX across all of Clerk's UI components. If you have used the appearance prop or tokens for 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 you will likely need to make adjustments to account for added or removed localization keys.

More detail on these changes »

In Core 2, defining redirect URLs for after sign-up, sign-in, or sign-out via the Clerk Dashboard has been removed. Previously, the "Paths" section in the Clerk Dashboard included "Component paths" where URLs could be defined, accompanied by a deprecation warning. This functionality is now removed, and specifying redirect paths via the dashboard is no longer supported.

If you need to pass a redirect URL for after sign-up, sign-in, or sign-out, there are several ways to achieve this, including environment variables, middleware, or passing 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.

- <UserButton afterSignOutUrl="/" />
+ <UserButton />

`afterSignXUrl` changes

Note

This section refers to afterSignXUrl where X could be Up or In depending on the context.

All afterSignXUrl props and CLERK_AFTER_SIGN_X_URL environment variables have been deprecated, and should be replaced by one of the following options:

CLERK_SIGN_X_FORCE_REDIRECT_URL / signXForceRedirectUrl – 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.
CLERK_SIGN_X_FALLBACK_REDIRECT_URL / signXFallbackRedirectUrl – If set, this will mirror the previous behavior, only redirecting to the provided URL if there is no redirect_url in the querystring.

In general, use the environment variables over the props.

Warning

If neither value is set, Clerk will redirect to the redirect_url if present, otherwise it will redirect to /.

To retain the current behavior of your app without any changes, you can switch afterSignXUrl with signXFallbackRedirectUrl as such:

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

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

@clerk/backend

import { createClerkClient } from '@clerk/backend'

const clerkClient = createClerkClient({ secretKey: '' })
const requestState = await clerkClient.authenticateRequest(request, { publishableKey: '' })
const claims: JwtPayload = requestState.toAuth().sessionClaims

Important

The Node SDK is no longer supported. Upgrade to the Express SDK.

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

If you would like to have your JWT return all of the user's organizations, you can create a custom JWT template in your dashboard. Add { "orgs": "user.organizations" } to it.

Path routing is now the default

On components like <SignIn /> you can define the props routing and path. routing describes the routing strategy that should be used and can be set to 'hash' | 'path'. path defines where the component is mounted when routing='path' is used. Learn more about Clerk routing.

In Core 2, the default routing strategy has become 'path' for the Remix SDK. Of course, you can still use routing='hash'.

<UserProfile routing="hash" />

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:

Deprecation removals & housekeeping

As part of this major version, a number of previously deprecated props, arguments, 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.

Note

For this section more than any other one, 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.

Deprecation removals

If you are updating a user's password via the User.update method, it must be changed to User.updatePassword 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 apiKey argument passed to createClerkClient must be changed to secretKey.

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

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

  import { rootAuthLoader } from '@clerk/remix/ssr.server'
  
- export const loader = (args) => rootAuthLoader(args, { apiKey: '...' })
+ export const loader = (args) => rootAuthLoader(args, { secretKey: '...' })

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

  import { getAuth } from '@clerk/remix/ssr.server'
  
  export const loader: LoaderFunction = async (args) => {
-   return getAuth(args, { apiKey: '...' })
+   return getAuth(args, { secretKey: '...' })
  }

The frontendApi argument passed to rootAuthLoader must be changed to publishableKey.

  import { rootAuthLoader } from '@clerk/remix/ssr.server'
  
- export const loader = (args) => rootAuthLoader(args, { frontendApi: '...' })
+ export const loader = (args) => rootAuthLoader(args, { publishableKey: '...' })

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:

- import Clerk from '@clerk/remix'
+ import { createClerkClient } from '@clerk/remix'

Other Breaking changes

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

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

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

The signOutCallback prop on the <SignOutButton /> component 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>
    )
  }

Edit on GitHub

Last updated on Aug 9, 2025

Upgrading @clerk/remix to Core 2

Feedback

Upgrading `@clerk/remix` to Core 2