refactor: use namespace React import and retain error in useAuth0Suspense

Author: gyaneshgouraw-okta

EXAMPLES.md

@@ -23,43 +23,6 @@
 - [Session Expiry from Upstream IdP (IPSIE)](#session-expiry-from-upstream-idp-ipsie)
 - [Use Suspense for loading state (React 19+)](#use-suspense-for-loading-state-react-19)
 
-## Use Suspense for loading state (React 19+)
-
-On React 19 and later, `useAuth0Suspense` lets a `<Suspense>` boundary handle the
-auth loading state and an Error Boundary handle initialization errors, so your
-component code stays focused on rendering. Unlike `useAuth0`, it does not return
-`isLoading` (the component suspends until auth is ready) or `error` (it is thrown
-to the nearest Error Boundary).
-
-```jsx
-import { Suspense } from 'react';
-import { Auth0Provider, useAuth0Suspense } from '@auth0/auth0-react';
-
-function App() {
-  return (
-    <Auth0Provider
-      domain="YOUR_DOMAIN"
-      clientId="YOUR_CLIENT_ID"
-      authorizationParams={{ redirect_uri: window.location.origin }}
-    >
-      <MyErrorBoundary fallback={<p>Could not sign you in.</p>}>
-        <Suspense fallback={<p>Loading...</p>}>
-          <UserGreeting />
-        </Suspense>
-      </MyErrorBoundary>
-    </Auth0Provider>
-  );
-}
-
-function UserGreeting() {
-  const { user, isAuthenticated } = useAuth0Suspense();
-  return isAuthenticated ? <p>Hello, {user?.name}!</p> : <p>Please log in</p>;
-}
-```
-
-`useAuth0Suspense` requires React 19; calling it on an earlier version throws a
-clear error. All the auth methods available on `useAuth0` (`loginWithRedirect`,
-`logout`, `getAccessTokenSilently`, etc.) are also available here.
 
 ## Use with a Class Component
 
@@ -1910,3 +1873,41 @@ function CallApi() {
 ```
 
 Using `withAuthenticationRequired` on protected routes is the simpler alternative — the redirect happens automatically without the null check.
+
+
+## Use Suspense for loading state (React 19+)
+
+On React 19 and later, `useAuth0Suspense` lets a `<Suspense>` boundary handle the
+auth loading state and an Error Boundary handle initialization errors, so your
+component code stays focused on rendering. Unlike `useAuth0`, it does not return
+`isLoading` — the component suspends until auth is ready.
+
+```jsx
+import { Suspense } from 'react';
+import { Auth0Provider, useAuth0Suspense } from '@auth0/auth0-react';
+
+function App() {
+  return (
+    <Auth0Provider
+      domain="YOUR_DOMAIN"
+      clientId="YOUR_CLIENT_ID"
+      authorizationParams={{ redirect_uri: window.location.origin }}
+    >
+      <MyErrorBoundary fallback={<p>Could not sign you in.</p>}>
+        <Suspense fallback={<p>Loading...</p>}>
+          <UserGreeting />
+        </Suspense>
+      </MyErrorBoundary>
+    </Auth0Provider>
+  );
+}
+
+function UserGreeting() {
+  const { user, isAuthenticated } = useAuth0Suspense();
+  return isAuthenticated ? <p>Hello, {user?.name}!</p> : <p>Please log in</p>;
+}
+```
+
+`useAuth0Suspense` requires React 19; calling it on an earlier version throws a
+clear error. All the auth methods available on `useAuth0` (`loginWithRedirect`,
+`logout`, `getAccessTokenSilently`, etc.) are also available here.

__tests__/use-auth0-suspense.test.tsx

@@ -106,6 +106,27 @@ describe('useAuth0Suspense', () => {
     );
   });
 
+  it('returns the auth methods, omitting isLoading and _initPromise', async () => {
+    clientMock.checkSession.mockResolvedValue(undefined);
+    clientMock.getUser.mockResolvedValue({ name: 'Bob' });
+
+    let captured: Record<string, unknown> | undefined;
+    function Capture() {
+      captured = useAuth0Suspense() as unknown as Record<string, unknown>;
+      return <div>captured</div>;
+    }
+
+    await renderWithProvider(<Capture />);
+    await waitFor(() =>
+      expect(screen.getByText('captured')).toBeInTheDocument()
+    );
+
+    expect(captured).not.toHaveProperty('isLoading');
+    expect(captured).not.toHaveProperty('_initPromise');
+    expect(captured).toHaveProperty('error');
+    expect(typeof captured!.loginWithRedirect).toBe('function');
+  });
+
   it('throws a clear error when used outside an Auth0Provider', () => {
     expect(() => renderHook(() => useAuth0Suspense())).toThrowError(
       /must be used within/

src/use-auth0-suspense.tsx

@@ -1,15 +1,18 @@
-import { use, useContext } from 'react';
+// Namespace import: `use` only exists as a named export from React 19, so
+// `import { use }` fails at link time for React 16-18 consumers even if they
+// never call this hook. Property access stays late-bound.
+import * as React from 'react';
 import { User } from '@auth0/auth0-spa-js';
 import Auth0Context, { Auth0ContextInterface } from './auth0-context';
 
 /**
  * The value returned by `useAuth0Suspense`: the full `useAuth0` interface minus
- * `isLoading` (always resolved by the time the hook returns) and `error`
- * (thrown to the nearest Error Boundary instead of returned).
+ * `isLoading` and the internal `_initPromise`. `error` is
+ * retained for post-init failures such as `loginWithPopup`.
  */
 export type Auth0SuspenseContextInterface<TUser extends User = User> = Omit<
   Auth0ContextInterface<TUser>,
-  'isLoading' | 'error'
+  'isLoading' | '_initPromise'
 >;
 
 /**
@@ -34,13 +37,13 @@ export type Auth0SuspenseContextInterface<TUser extends User = User> = Omit<
 const useAuth0Suspense = <TUser extends User = User>(
   context = Auth0Context
 ): Auth0SuspenseContextInterface<TUser> => {
-  if (typeof use !== 'function') {
+  if (typeof React.use !== 'function') {
     throw new Error(
       'useAuth0Suspense requires React 19 or later (React.use is unavailable).'
     );
   }
 
-  const ctx = useContext(context) as Auth0ContextInterface<TUser>;
+  const ctx = React.useContext(context) as Auth0ContextInterface<TUser>;
 
   if (!ctx._initPromise) {
     throw new Error(
@@ -49,10 +52,10 @@ const useAuth0Suspense = <TUser extends User = User>(
   }
 
   // Suspends until the init promise resolves; re-throws if it rejected.
-  use(ctx._initPromise);
+  React.use(ctx._initPromise);
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { isLoading, error, ...rest } = ctx;
+  const { isLoading, _initPromise, ...rest } = ctx;
   return rest;
 };