fix(upgrade): Add missing Core 3 upgrade guide entries (#7888)

Author: jacekradko

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

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|Up|Out)Button[\s\S]*?\bas\b'
+matcherFlags: 'm'
+category: 'deprecation-removal'
+---
+
+The deprecated `as` prop has been removed from unstyled button components in `@clerk/astro`. Use the `asChild` prop with a custom element in the default slot instead.
+
+Affected components: `SignInButton`, `SignUpButton`, `SignOutButton`, `CheckoutButton`, `PlanDetailsButton`, `SubscriptionDetailsButton`.
+
+```diff
+- <SignInButton as="a" href="/sign-in">
+-   Sign in
+- </SignInButton>
++ <SignInButton asChild>
++   <a href="/sign-in">Sign in</a>
++ </SignInButton>
+```

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: '<ClerkProvider'
+category: 'breaking'
+warning: true
+---
+
+The `publishableKey` prop is now required in `ClerkProvider` for Expo apps. Previously, it would fall back to the `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` or `CLERK_PUBLISHABLE_KEY` environment variables, but environment variables inside `node_modules` are not inlined during production builds in React Native/Expo, which could cause apps to crash in production.
+
+```diff
++ const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!;
+
+- <ClerkProvider>
++ <ClerkProvider publishableKey={publishableKey}>
+    {/* Your app */}
+  </ClerkProvider>
+```

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()`.

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.

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
+```

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);
+```

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';
+-
+- <ClerkProvider appearance={{ baseTheme: __experimental_simple }}>
++ <ClerkProvider appearance={{ theme: 'simple' }}>
+    {/* Your app */}
+  </ClerkProvider>
+```