Upgrading to Clerk Core 3

The authorization control components <Protect>, <SignedIn>, and <SignedOut> have been removed in favor of a single component: <Show>.

Signed in / signed out

Authorization checks (roles/permissions/features/plans)

If you were using condition={(has) => ...} on Protect, pass that callback to when:

The appearance.layout property has been renamed to appearance.options. Update all instances in your codebase:

The colorRing and colorModalBackdrop CSS variables now render at full opacity when modified via the appearance prop or CSS variables. Previously, provided colors were rendered at 15% opacity.

If you were relying on the Core 2 behavior, you may need to adjust your color values to include the desired opacity:

The return values of the useCheckout hook and the Clerk.checkout() method have been updated.

React hook

Vanilla JS

All experimental methods now use the __experimental_ prefix consistently. Update any references:

The createTheme theme utility has been moved to a new export path. Update your imports:

All __unstable_* methods have been renamed to __internal_*. These are internal APIs not intended for public use.

@clerk/clerk-js

• __unstable__environment → __internal_environment
• __unstable__updateProps → __internal_updateProps
• __unstable__setEnvironment → __internal_setEnvironment
• __unstable__onBeforeRequest → __internal_onBeforeRequest
• __unstable__onAfterResponse → __internal_onAfterResponse
• __unstable__onBeforeSetActive → __internal_onBeforeSetActive
• __unstable__onAfterSetActive → __internal_onAfterSetActive

@clerk/nextjs

• __unstable_invokeMiddlewareOnAuthStateChange → __internal_invokeMiddlewareOnAuthStateChange

@clerk/chrome-extension

• __unstable__createClerkClient → createClerkClient (exported from @clerk/chrome-extension/background)

getToken() now throws a ClerkOfflineError instead of returning null when the browser is offline. This makes it explicit that the request failed due to network conditions, not because the user is signed out.

ClerkOfflineError is available from @clerk/react/errors, @clerk/nextjs/errors, @clerk/vue/errors, and other SDK error entry points. The error is thrown after a short retry period (~15 seconds) to handle temporary network issues. getToken() still returns null when the user is not signed in.

useAuth().getToken is no longer undefined during server-side rendering. It is now a function that throws a clerk_runtime_not_browser error when called on the server.

If you were checking getToken === undefined to avoid calling it during SSR, update your code:

If you only use getToken in useEffect, event handlers, or with non-suspenseful data fetching libraries, no change is necessary as these only run on the client.

A new sign-in status of needs_client_trust has been added. If your application has passwords and Client Trust enabled, you'll need to handle this new status in your sign-in flow:

This status is returned when passwords and Client Trust are enabled, the needs_client_trust update is opted-in, and email/phone identifiers are enabled without email/SMS sign-in verification.

The simple theme is no longer exported directly from @clerk/ui. Use the appearance prop to apply it instead:

The clerkJSUrl, clerkJSVersion, clerkUIUrl, and clerkUIVersion props have been removed from ClerkProvider and related configuration options. These props were intended for internal use and are no longer part of the public API.

If you need to pin a specific version of the UI, import ui from @clerk/ui and pass it to ClerkProvider:

The clerkJSVariant prop has been removed. Use prefetchUI={false} instead to disable prefetching the UI bundle:

You can also disable UI prefetching via environment variable:

• Next.js: NEXT_PUBLIC_CLERK_PREFETCH_UI=false
• Astro: PUBLIC_CLERK_PREFETCH_UI=false
• React Router / TanStack Start: CLERK_PREFETCH_UI=false

The afterSwitchOrganizationUrl prop has been removed from OrganizationSwitcher. Use afterSelectOrganizationUrl instead:

The activeSessions property has been removed from the Client object. Use sessions instead:

The hideSlug prop has been removed. Organization slugs are now managed through the Clerk Dashboard.

To hide organization slugs, navigate to the Organizations Settings⁠ page in the Clerk Dashboard, and ensure that the Enable organization slugs option is disabled.

The saml authentication strategy has been renamed to enterprise_sso. Update any references in your code:

The samlAccount property has been renamed to enterpriseAccount. Update your code:

The beforeEmit callback in setActive() has been replaced with navigate. The callback signature has also changed:

The navigate callback receives an object with the session property and the decorateUrl function. Learn more about the navigate callback.

The UserButton component no longer accepts sign-out redirect override props. Configure sign-out redirects using one of these methods:

Global configuration:

Per-button with SignOutButton:

Programmatic:

The saml property on UserSettings has been renamed to enterpriseSSO. Update your code:

The legacy redirect props afterSignInUrl, afterSignUpUrl, and redirectUrl have been removed from components. Use the newer redirect options:

For forced redirects that ignore the redirect_url query parameter:

The following unstable properties have been removed. If you were relying on these, please reach out to our support team⁠.

• __unstable_manageBillingUrl
• __unstable_manageBillingLabel
• __unstable_manageBillingMembersLimit

The deprecated verifySecret(), verifyAccessToken(), and verifyToken() methods have been removed from @clerk/backend. Use verify() instead:

The @clerk/types package is deprecated. All type definitions have been consolidated into @clerk/shared/types.

Update your imports:

The @clerk/types package will continue to re-export types from @clerk/shared/types for backward compatibility, but new types will only be added to @clerk/shared/types.

All Clerk packages now require Node.js 20.9.0 or later. Update your Node.js version and ensure your package.json engines field reflects this requirement.

The default value of appearance.layout.showOptionalFields (now appearance.options.showOptionalFields) has changed from true to false. Optional fields are now hidden by default during sign up.

To restore the Core 2 behavior, explicitly set the option:

ClerkAPIError.kind has been updated to match the class name:

Most users should not be affected. If you were checking this string directly (e.g., error.constructor.kind === 'ClerkApiError'), update the comparison value.

In Core 2, satellite applications automatically synced authentication state with the primary domain on every first page load by redirecting users to the primary domain and back. This happened regardless of whether the user had an active session, which caused unnecessary latency for apps where most visitors are anonymous.

In Core 3, this behavior is controlled by the satelliteAutoSync option, which defaults to false. This means satellite apps no longer perform automatic redirects on first visit and users are not automatically recognized on the satellite domain unless they select "Sign in".

To restore the Core 2 behavior, in the your satellite domain's app, set satelliteAutoSync to true in your middleware and <ClerkProvider> component.

If you have any questions about satellite domains, or you're having any trouble setting this up, see the guide on satellite domains or contact support@clerk.com

session.getToken() now implements a stale-while-revalidate pattern that improves performance by returning cached tokens immediately while refreshing them in the background when they're close to expiration.

When a token is within 15 seconds of expiration, getToken() returns the valid cached token immediately and triggers a background refresh. Subsequent calls receive the new token once the background refresh completes. Token updates are automatically synchronized across browser tabs using BroadcastChannel.

This is a transparent improvement — no code changes are required. Your existing getToken() calls benefit automatically.