From 2445b6b1e625678b47044ba5f21b7c6ac57009ec Mon Sep 17 00:00:00 2001 From: Jacek Date: Thu, 19 Feb 2026 13:38:05 -0600 Subject: [PATCH 1/3] fix(upgrade): Add missing Core 3 upgrade guide entries for breaking changes --- .../core-3/changes/astro-as-prop-removed.md | 20 ++++++++++ .../changes/expo-publishable-key-required.md | 18 +++++++++ .../core-3/changes/gettoken-ssr-throws.md | 31 +++++++++++++++ .../core-3/changes/nextjs-min-version.md | 20 ++++++++++ .../react-router-api-server-removed.md | 19 +++++++++ .../react-router-require-middleware.md | 39 +++++++++++++++++++ .../changes/simple-theme-usage-changed.md | 19 +++++++++ 7 files changed, 166 insertions(+) create mode 100644 packages/upgrade/src/versions/core-3/changes/astro-as-prop-removed.md create mode 100644 packages/upgrade/src/versions/core-3/changes/expo-publishable-key-required.md create mode 100644 packages/upgrade/src/versions/core-3/changes/gettoken-ssr-throws.md create mode 100644 packages/upgrade/src/versions/core-3/changes/nextjs-min-version.md create mode 100644 packages/upgrade/src/versions/core-3/changes/react-router-api-server-removed.md create mode 100644 packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md create mode 100644 packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md diff --git a/packages/upgrade/src/versions/core-3/changes/astro-as-prop-removed.md b/packages/upgrade/src/versions/core-3/changes/astro-as-prop-removed.md new file mode 100644 index 00000000000..dd8192af760 --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/astro-as-prop-removed.md @@ -0,0 +1,20 @@ +--- +title: '`as` prop removed from Astro button components' +packages: ['astro'] +matcher: ' +- Sign in +- ++ ++ Sign in ++ +``` diff --git a/packages/upgrade/src/versions/core-3/changes/expo-publishable-key-required.md b/packages/upgrade/src/versions/core-3/changes/expo-publishable-key-required.md new file mode 100644 index 00000000000..dd4a6e4c2db --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/expo-publishable-key-required.md @@ -0,0 +1,18 @@ +--- +title: '`publishableKey` prop required in Expo `ClerkProvider`' +packages: ['expo'] +matcher: ' ++ + {/* Your app */} + +``` diff --git a/packages/upgrade/src/versions/core-3/changes/gettoken-ssr-throws.md b/packages/upgrade/src/versions/core-3/changes/gettoken-ssr-throws.md new file mode 100644 index 00000000000..b4bb5ee2414 --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/gettoken-ssr-throws.md @@ -0,0 +1,31 @@ +--- +title: '`useAuth().getToken` is no longer `undefined` during SSR' +matcher: 'getToken' +category: 'breaking' +--- + +`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 to catch the error instead: + +```diff +- if (getToken) { +- const token = await getToken(); +- } ++ try { ++ const token = await getToken(); ++ } catch (error) { ++ if (isClerkRuntimeError(error) && error.code === 'clerk_runtime_not_browser') { ++ // Handle server-side scenario ++ } ++ } +``` + +### Who is affected + +- 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. +- If you were using `getToken === undefined` checks to avoid calling it during SSR, update to use try-catch error handling. + +### Server-side auth + +To access auth data server-side, use the [`Auth` object](https://clerk.com/docs/reference/backend/types/auth-object) provided by your SDK instead of `useAuth()`. diff --git a/packages/upgrade/src/versions/core-3/changes/nextjs-min-version.md b/packages/upgrade/src/versions/core-3/changes/nextjs-min-version.md new file mode 100644 index 00000000000..7006ee1e3c0 --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/nextjs-min-version.md @@ -0,0 +1,20 @@ +--- +title: 'Minimum Next.js version increased to 15.2.3' +packages: ['nextjs'] +matcher: "next\":\\s*\"(?:\\^|~|>|=|\\s)*(?:13|14)\\." +matcherFlags: 'm' +category: 'version' +--- + +Support for Next.js 13 and 14 has been dropped. `@clerk/nextjs` now requires `next@>=15.2.3`. + +```diff +{ + "dependencies": { +- "next": "^14.0.0", ++ "next": "^15.2.3", + } +} +``` + +See the [Next.js upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading) for help migrating your application. diff --git a/packages/upgrade/src/versions/core-3/changes/react-router-api-server-removed.md b/packages/upgrade/src/versions/core-3/changes/react-router-api-server-removed.md new file mode 100644 index 00000000000..c2dca7e1270 --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/react-router-api-server-removed.md @@ -0,0 +1,19 @@ +--- +title: '`@clerk/react-router/api.server` export removed' +packages: ['react-router'] +matcher: '@clerk/react-router/api.server' +category: 'breaking' +--- + +The `@clerk/react-router/api.server` export has been removed. Use `@clerk/react-router/server` instead. + +```diff +- import { getAuth } from '@clerk/react-router/api.server'; ++ import { getAuth } from '@clerk/react-router/server'; +``` + +A codemod is available to automatically apply this change: + +```bash +npx @clerk/upgrade --release core-3 +``` diff --git a/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md b/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md new file mode 100644 index 00000000000..783f17818f9 --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md @@ -0,0 +1,39 @@ +--- +title: '`rootAuthLoader` requires `clerkMiddleware()` in React Router' +packages: ['react-router'] +matcher: 'rootAuthLoader' +category: 'breaking' +--- + +`rootAuthLoader` now requires `clerkMiddleware()` to be installed. Using `rootAuthLoader` without middleware will throw a runtime error. + +### Before (Core 2) + +```tsx +import { rootAuthLoader } from '@clerk/react-router/ssr.server' + +export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args) +``` + +### After (Core 3) + +1. Enable the `v8_middleware` future flag: + +```ts +// react-router.config.ts +export default { + future: { + v8_middleware: true, + }, +} satisfies Config; +``` + +2. Use `clerkMiddleware()` alongside `rootAuthLoader`: + +```tsx +import { clerkMiddleware, rootAuthLoader } from '@clerk/react-router/server' + +export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()] + +export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args) +``` diff --git a/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md b/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md new file mode 100644 index 00000000000..b5c852de642 --- /dev/null +++ b/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md @@ -0,0 +1,19 @@ +--- +title: '`simple` theme export removed from `@clerk/ui`' +matcher: + - "import.*simple.*from.*@clerk/ui" + - '__experimental_simple' + - 'experimental__simple' +category: 'breaking' +--- + +The `simple` theme is no longer exported directly from `@clerk/ui`. Use the `appearance` prop to apply it instead: + +```diff +- import { __experimental_simple } from '@clerk/ui'; +- +- ++ + {/* Your app */} + +``` From 33b1a06dcbe6598bf016ac22f9811c7dcbf10735 Mon Sep 17 00:00:00 2001 From: Jacek Date: Thu, 19 Feb 2026 13:41:18 -0600 Subject: [PATCH 2/3] chore: Add changeset --- .changeset/add-missing-upgrade-entries.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/add-missing-upgrade-entries.md diff --git a/.changeset/add-missing-upgrade-entries.md b/.changeset/add-missing-upgrade-entries.md new file mode 100644 index 00000000000..5573f3f4bb5 --- /dev/null +++ b/.changeset/add-missing-upgrade-entries.md @@ -0,0 +1,5 @@ +--- +"@clerk/upgrade": patch +--- + +Add missing Core 3 upgrade guide entries for breaking changes: `getToken` SSR behavior, React Router middleware requirement, Expo `publishableKey` requirement, Astro `as` prop removal, `simple` theme export change, React Router `api.server` removal, and Next.js minimum version bump. From 9ab62138ae101a76589181f65ccd7734a33713e9 Mon Sep 17 00:00:00 2001 From: Jacek Date: Thu, 19 Feb 2026 13:50:13 -0600 Subject: [PATCH 3/3] chore: Fix prettier formatting --- .../core-3/changes/react-router-require-middleware.md | 10 +++++----- .../core-3/changes/simple-theme-usage-changed.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md b/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md index 783f17818f9..feb365a8af5 100644 --- a/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md +++ b/packages/upgrade/src/versions/core-3/changes/react-router-require-middleware.md @@ -10,9 +10,9 @@ category: 'breaking' ### Before (Core 2) ```tsx -import { rootAuthLoader } from '@clerk/react-router/ssr.server' +import { rootAuthLoader } from '@clerk/react-router/ssr.server'; -export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args) +export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args); ``` ### After (Core 3) @@ -31,9 +31,9 @@ export default { 2. Use `clerkMiddleware()` alongside `rootAuthLoader`: ```tsx -import { clerkMiddleware, rootAuthLoader } from '@clerk/react-router/server' +import { clerkMiddleware, rootAuthLoader } from '@clerk/react-router/server'; -export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()] +export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()]; -export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args) +export const loader = (args: Route.LoaderArgs) => rootAuthLoader(args); ``` diff --git a/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md b/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md index b5c852de642..381261f4d6e 100644 --- a/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md +++ b/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md @@ -1,7 +1,7 @@ --- title: '`simple` theme export removed from `@clerk/ui`' matcher: - - "import.*simple.*from.*@clerk/ui" + - 'import.*simple.*from.*@clerk/ui' - '__experimental_simple' - 'experimental__simple' category: 'breaking'