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. 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..feb365a8af5 --- /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..381261f4d6e --- /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 */} + +```