feat(nextjs,react,shared): Support suspenseful initialState (#7759)

Author: Ephem

.changeset/silly-peaches-march.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/react': patch
+---

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -36,7 +36,9 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
 
   const propsWithEnvs = mergeNextClerkPropsWithEnv({
     ...rest,
-    initialState: (await statePromiseOrValue) as InitialState | undefined,
+    // Even though we always cast to InitialState here, this might still be a promise.
+    // While not reflected in the public types, we do support this for React >= 19 for internal use.
+    initialState: statePromiseOrValue as InitialState | undefined,
     nonce: await noncePromiseOrValue,
   });
 

packages/react/src/types.ts

@@ -41,7 +41,7 @@ export type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOption
   /**
    * Provide an initial state of the Clerk client during server-side rendering. You don't need to set this value yourself unless you're [developing an SDK](https://clerk.com/docs/guides/development/sdk-development/overview).
    */
-  initialState?: InitialState;
+  initialState?: InitialState; // For React >= 19, Promise<InitialState> is also supported for internal use, but not reflected in the types
   /**
    * Indicates to silently fail the initialization process when the publishable keys is not provided, instead of throwing an error.
    * @default false

packages/shared/src/react/ClerkContextProvider.tsx

@@ -12,14 +12,19 @@ type ClerkContextProps = {
   clerk: Clerk;
   clerkStatus?: ClerkStatus;
   children: React.ReactNode;
-  initialState?: InitialState;
+  initialState?: InitialState | Promise<InitialState>;
 };
 
 export function ClerkContextProvider(props: ClerkContextProps): JSX.Element | null {
   const clerk = props.clerk as LoadedClerk;
 
   assertClerkSingletonExists(clerk);
 
+  // The initialState hook has the same check, but it's better to fail early
+  if (props.initialState instanceof Promise && !('use' in React && typeof React.use === 'function')) {
+    throw new Error('initialState cannot be a promise if React version is less than 19');
+  }
+
   const clerkCtx = React.useMemo(
     () => ({ value: clerk }),
     // clerkStatus is a way to control the referential integrity of the clerk object from the outside,

packages/shared/src/react/contexts.tsx

@@ -19,14 +19,16 @@ export { useUserBase as useUserContext } from './hooks/base/useUserBase';
 export { useClientBase as useClientContext } from './hooks/base/useClientBase';
 export { useSessionBase as useSessionContext } from './hooks/base/useSessionBase';
 
-const [InitialStateContext, _useInitialStateContext] = createContextAndHook<InitialState | undefined>(
-  'InitialStateContext',
-);
+const [InitialStateContext, _useInitialStateContext] = createContextAndHook<
+  InitialState | Promise<InitialState> | undefined
+>('InitialStateContext');
 
 /**
  * Provides initial Clerk state (session, user, organization data) from server-side rendering
  * to child components via React context.
  *
+ * Passing in a promise is only supported for React >= 19.
+ *
  * The initialState is snapshotted on mount and cannot change during the component lifecycle.
  *
  * Note that different parts of the React tree can use separate InitialStateProvider instances
@@ -37,7 +39,7 @@ export function InitialStateProvider({
   initialState,
 }: {
   children: React.ReactNode;
-  initialState: InitialState | undefined;
+  initialState: InitialState | Promise<InitialState> | undefined;
 }) {
   // The initialState is not allowed to change, we snapshot it to turn that expectation into a guarantee.
   // Note that despite this, it could still be different for different parts of the React tree which is fine,
@@ -51,9 +53,13 @@ export function InitialStateProvider({
 export function useInitialStateContext(): InitialState | undefined {
   const initialState = _useInitialStateContext();
 
-  // If we want to support passing initialState as a promise, this is where we would handle that.
-  // Note that we can not use(promise) as long as we support React 18, so we'll need to have some extra handling
-  // and throw the promise instead.
+  if (initialState instanceof Promise) {
+    if ('use' in React && typeof React.use === 'function') {
+      return React.use(initialState);
+    } else {
+      throw new Error('initialState cannot be a promise if React version is less than 19');
+    }
+  }
 
   return initialState;
 }