npm / @clerk/nextjs
@clerk/nextjs
What changed in @clerk/nextjs 6 to 7, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
39 breaking10 security5 deprecations26 new APIs and options6 behavior and defaults14 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@clerk/nextjs 790 changes
Breaking changes 39
Missing Clerk keys no longer activate keyless mode; the SDK throws an error directing you to run npx clerk@latest init to provision an application and write keys to .env.local.
Using the removed Protect component now triggers a runtime migration error.
Using the removed SignedIn component now triggers a runtime migration error.
Using the removed SignedOut component now triggers a runtime migration error.
Removed the component from the public API in favor of usage within OrganizationProfile.
Middleware authorization now fails closed during the keyless bootstrap window, preventing auth.protect() and custom authorization checks from being bypassed while the publishable key is being provisioned.
Legacy redirect props are no longer exported; components rely on new redirect options and server-side configuration.
Legacy redirect props are no longer exported; components rely on new redirect options and server-side configuration.
OrganizationSwitcher no longer exports this prop.
Unauthenticated server action requests now receive 401 instead of 404.
When passing secretKey as a runtime option to clerkMiddleware(), a missing encryption key now throws; configure this environment variable.
Removed from all SDKs; pin @clerk/clerk-js by passing its Clerk constructor to ClerkProvider via the Clerk prop.
Removed along with the headless bundle; use prefetchUI={false} instead.
Removed from all SDKs; pin @clerk/clerk-js by passing its Clerk constructor to ClerkProvider via the Clerk prop.
This type alias is no longer exported.
Removed from all SDKs; pass ui from @clerk/ui to ClerkProvider via the ui prop to pin a version.
Removed from all SDKs; pass ui from @clerk/ui to ClerkProvider via the ui prop to pin a version.
No longer exported.
Methods previously prefixed experimental__* and experimental_* are renamed to __experimental_* for beta features.
Removed deprecated option.
When the client is offline, getToken() now throws ClerkOfflineError instead of returning null.
Organization hideSlug flags are no longer exported.
useAuth no longer accepts initialAuthState; pass initialState to ClerkProvider or use dynamic with the Next package.
Methods previously prefixed __unstable_* are renamed to __internal_* for internal APIs.
Renamed from __unstable_invokeMiddlewareOnAuthStateChange.
Support for Next.js 13 and 14 is dropped; Next.js >=15.2.3 is required.
The minimum supported Node version is now v20.9.0.
Use prefetchUI={false} in place of the removed clerkJSVariant option and headless bundle.
Removed in favor of Show.
Legacy redirect props are no longer exported; components rely on new redirect options and server-side configuration.
The beforeEmit option is no longer exported.
Introduced as the cross-framework authorization control component, replacing Protect, SignedIn, and SignedOut.
Removed in favor of Show.
Removed in favor of Show.
Removed deprecated billing-related prop.
Removed deprecated billing-related prop.
Removed deprecated billing-related prop.
During SSR, getToken is now a function rather than undefined, and calling it throws; handle the error instead of checking for undefined.
UserButton sign-out overrides are no longer exported.
Security 10
Isolates each request's store so dynamic secret keys used by clerkClient() inside the middleware handler cannot leak across concurrent requests.
CSP headers generated by clerkMiddleware() now allow Clerk abuse and fraud protection resources.
Known credential keys are now recursively truncated at any nesting depth, preventing bearer tokens from reaching debug logs.
Keyless mode no longer activates in CI and other automated environments.
If you use the Next.js App Router, upgrade to Next.js 15.5.18, 16.2.6, or a later patched release; versions 16.0.0 through 16.2.5 remain affected by a Middleware/Proxy bypass.
Middleware-to-origin auth header integrity signatures are now compared in constant time, avoiding timing-variable validation and working in both Node and Edge Runtime.
URL paths are normalized to prevent route protection bypass.
Official Clerk JavaScript SDKs: Middleware-based route protection bypass
If you use the Next.js App Router, upgrade Next.js to 15.5.15 or 16.2.3 to address a high-severity React Server Components denial-of-service vulnerability.
The generated CSP nonce is now forwarded as a request header, allowing server components and ClerkProvider to apply it to script tags.
Deprecations 5
The removed control-component stub is now tagged @deprecated, so editors and lint rules flag use at authoring time and provide <Show> migration guidance.
The removed control-component stub is now tagged @deprecated, so editors and lint rules flag use at authoring time and provide <Show> migration guidance.
The removed control-component stub is now tagged @deprecated, so editors and lint rules flag use at authoring time and provide <Show> migration guidance.
Deprecated in favor of resource-based auth checks, which place checks in each protected page, layout, API route, or Server Function.
The existing type remains unchanged but is now deprecated.
New APIs and options 23
Adds an authenticated component for approving or denying OAuth Device Authorization Grant requests.
Adds a workflow hook for approving or denying OAuth Device Authorization Grant requests.
Frontend API proxy helpers accept an fapiUrl option so requests can target a custom Clerk Frontend API URL.
Set CLERK_DISABLE_AUTO_PROXY=true to opt out of automatic Frontend API proxying on Vercel production deployments.
Exported as the new type-level autocomplete suggestion for route matchers, using the :path* subtree form.
Exported this previously internal type so it can be referenced from generated docs.
Exported this previously internal type so it can be referenced from generated docs.
Exported this previously internal type so it can be referenced from generated docs.
Exposed OAuthConsent as a public component export across React-based SDKs.
Re-exports the useAPIKeys() hook from @clerk/nextjs so applications can use it directly.
New /types subpath re-exports shared and SDK-specific types so applications can import Clerk types directly from the SDK package.
New query parameter tracks satellite sync state: 1 triggers handshake after primary sign-in and 2 prevents a re-sync loop after completion.
Exported error to identify offline token-fetch failures from getToken().
New ui prop accepts @clerk/ui, enabling the UI module to be passed directly to ClerkProvider.
Adds Frontend API proxy support through the clerkMiddleware option.
Standalone function retrieves session tokens outside framework component trees and waits for Clerk to initialize in the browser.
Component handles the SSO callback during custom flows, including sign-in-or-up.
Defaults to false, skipping automatic satellite handshake when no session cookies exist; set true to retain automatic first-load syncing.
Introduces a session task named setup_mfa.
Option disables the development mode warning emitted to the console when Clerk is first loaded.
Component lets developers choose the container for Clerk floating UI portals within its provider subtree.
Exported hook fetches a suggested organization name and logo from default naming rules.
Exports for the useWaitlist hook were added.
Behavior and default changes 5
The default Content Security Policy no longer includes https://images.clerkstage.dev, a Clerk-internal storage host that applications do not connect to.
The generated connect-src directive allows Clerk abuse and fraud protection hosts on all ports, so requests to those hosts on non-443 ports are no longer blocked.
ConfigureSSO is no longer on the experimental path.
On
.vercel.appdomains without explicit proxy or domain configuration, Frontend API requests are automatically routed through/__clerkon the app's own origin, enabling Clerk production mode without manual proxy setup.Image CDNs are now included in the Content Security Policy connect-src directive.
Fixes and other changes 8
Export <HandleSSOCallback /> from @clerk/nextjs so it can be used on the SSO callback route of a custom flow.
Removed the trailing period from the displayed error so agents do not append it to the URL and get a 404.
Fixes a development-only React key warning when using ClerkProvider in the App Router.
Fixed a stray double space in the error message about Clerk not detecting usage of clerkMiddleware().
The error message when clerkMiddleware is not detected now notes that infrastructure issues, such as edge runtime errors or platform outages, can also cause the error.
Fixes build failures when cacheComponents is enabled with dynamic routes such as [id].
Fixed an edge case where duplicate in-flight redirects to the same destination could leave awaitable navigation pending indefinitely.
Improved error detection and messages when auth() or currentUser() are called inside a use cache function.
@clerk/nextjs 610 changes
New APIs and options 3
M2M token creation accepts tokenFormat: 'jwt'; JWT-format tokens can be verified with clerkClient.m2m.verify, including networkless verification using the public JWT key.
Introduces an MFA setup session task for handling require MFA after sign-in and sign-up.
Introduces the TaskResetPassword session task component for handling password resets.
Behavior and default changes 1
Updates the supported API version to 2025-11-10.
Fixes and other changes 6
Fixes an infinite handshake redirect loop when deploying Next.js apps with Clerk development instances to Netlify.
JWT OAuth access tokens are now treated as machine tokens.
Updates the middleware location check to account for proxy.ts in Next 16+ applications.
React 19 peer dependency ranges use ~ instead of ^ to ensure non-overlapping version constraints.
Extends the cache invalidation no-op to Next.js 16 during sign-out.
Added support for Next.js 16.