chore(expo): Remove Clerk instance export (#7519)

Co-authored-by: Christopher Canin <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 3 people

.changeset/tame-carpets-sink.md

@@ -0,0 +1,29 @@
+---
+'@clerk/expo': major
+---
+
+Remove deprecated `Clerk` export in favor of `getClerkInstance()`.
+
+```diff
+- import { Clerk } from '@clerk/clerk-expo';
++ import { getClerkInstance } from '@clerk/expo';
+
+- const token = await Clerk.session?.getToken();
++ const token = await getClerkInstance().session?.getToken();
+```
+
+If you need to create the instance before `ClerkProvider` renders, pass the `publishableKey`:
+
+```tsx
+import { ClerkProvider, getClerkInstance } from '@clerk/expo';
+
+const clerkInstance = getClerkInstance({ publishableKey: 'pk_xxx' });
+
+// Use the instance outside of React
+const token = await clerkInstance?.session?.getToken();
+fetch('https://example.com/api', { headers: { Authorization: `Bearer ${token}` } });
+```
+
+> [!NOTE]
+> - Calling `getClerkInstance()` with different publishable keys will create a new Clerk instance.
+> - If `getClerkInstance` is called without a publishable key, and `ClerkProvider` has not rendered yet, an error will be thrown.

packages/expo/src/index.ts

@@ -8,10 +8,6 @@ export {
   isClerkRuntimeError,
 } from '@clerk/react/errors';
 
-/**
- * @deprecated Use `getClerkInstance()` instead.
- */
-export { clerk as Clerk } from './provider/singleton';
 export { getClerkInstance } from './provider/singleton';
 
 export * from './provider/ClerkProvider';

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -25,10 +25,6 @@ import type { BuildClerkOptions } from './types';
 
 const KEY = '__clerk_client_jwt';
 
-/**
- * @deprecated Use `getClerkInstance()` instead. `Clerk` will be removed in the next major version.
- */
-export let clerk: HeadlessBrowserClerk | BrowserClerk;
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
@@ -53,7 +49,7 @@ export function createClerkInstance(ClerkClass: typeof Clerk) {
 
       const getToken = tokenCache.getToken;
       const saveToken = tokenCache.saveToken;
-      __internal_clerk = clerk = new ClerkClass(publishableKey);
+      __internal_clerk = new ClerkClass(publishableKey);
 
       if (Platform.OS === 'ios' || Platform.OS === 'android') {
         // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/singleton.ts

@@ -2,11 +2,6 @@ import { Clerk } from '@clerk/clerk-js/headless';
 
 import { createClerkInstance } from './createClerkInstance';
 
-/**
- * @deprecated Use `getClerkInstance()` instead. `Clerk` will be removed in the next major version.
- */
-export { clerk } from './createClerkInstance';
-
 /**
  * Access or create a Clerk instance outside of React. If you are using it in Expo Web then it will only access the existing instance from `window.Clerk`
  * @example

packages/expo/src/provider/singleton/singleton.web.ts

@@ -3,12 +3,8 @@ import type { BrowserClerk, HeadlessBrowserClerk } from '@clerk/react';
 import type { BuildClerkOptions } from './types';
 
 /**
- * @deprecated Use `getClerkInstance()` instead. `Clerk` will be removed in the next major version.
- */
-export const clerk = globalThis?.window?.Clerk;
-
-/**
- * No need to use options here as we are not creating a new instance of Clerk, we are just getting the existing instance from the window
+ * Access the existing Clerk instance from `window.Clerk` on the web.
+ * Unlike the native implementation, this does not create a new instance—it only returns the existing one set by ClerkProvider.
  */
 export const getClerkInstance = (_options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk | undefined =>
   globalThis?.window?.Clerk;

packages/upgrade/src/versions/core-3/changes/expo-clerk-export-removed.md

@@ -0,0 +1,32 @@
+---
+title: '`Clerk` export removed from `@clerk/expo`'
+matcher: "import\\s+\\{[^}]*\\bClerk\\b[^}]*\\}\\s+from\\s+['\"]@clerk/(clerk-)?expo['\"]"
+matcherFlags: 'm'
+category: 'deprecation-removal'
+---
+
+The deprecated `Clerk` export has been removed from `@clerk/expo`. Use `getClerkInstance()` instead.
+
+```diff
+- import { Clerk } from '@clerk/clerk-expo';
++ import { getClerkInstance } from '@clerk/expo';
+
+- const token = await Clerk.session?.getToken();
++ const token = await getClerkInstance().session?.getToken();
+```
+
+If you need to create the instance before `ClerkProvider` renders, pass the `publishableKey`:
+
+```tsx
+import { ClerkProvider, getClerkInstance } from '@clerk/expo';
+
+const clerkInstance = getClerkInstance({ publishableKey: 'pk_xxx' });
+
+// Use the instance outside of React
+const token = await clerkInstance.session?.getToken();
+```
+
+> [!NOTE]
+>
+> - Calling `getClerkInstance()` with different publishable keys will create a new Clerk instance.
+> - If `getClerkInstance` is called without a publishable key, and `ClerkProvider` has not rendered yet, an error will be thrown.