fix: seed useUser with auth.currentUser to prevent undefined on initial render

src/auth.tsx

@@ -25,7 +25,17 @@ export function useUser<T = unknown>(options?: ReactFireOptions<T>): ObservableS
   const observableId = `auth:user:${auth.name}`;
   const observable$ = user(auth);
 
-  return useObservable(observableId, observable$, options);
+  const _options: ReactFireOptions<T> = { ...options };
+
+  // If a user is already signed in, seed initialData so consumers see the user
+  // synchronously on the first render without waiting for the async observable.
+  // We only do this when currentUser is truthy to avoid masking the uninitialized
+  // (null before auth has loaded from storage) case as "signed out".
+  if (auth.currentUser && !('initialData' in _options) && !('startWithValue' in _options)) {
+    _options.initialData = auth.currentUser as unknown as T;
+  }
+
+  return useObservable(observableId, observable$, _options);
 }
 
 export function useIdTokenResult(user: User, forceRefresh = false, options?: ReactFireOptions<IdTokenResult>): ObservableStatus<IdTokenResult> {

src/useObservable.ts

@@ -125,11 +125,24 @@ export function useObservable<T = unknown>(observableId: string, source: Observa
 
   const update = useSyncExternalStore(subscribe, getSnapshot);
 
-  // modify the value if initialData exists
+  // Return a new object with initialData overlaid rather than mutating the shared
+  // _immutableStatus reference, which is the same object across all components
+  // using the same observableId.
   if (!observable.hasValue && hasData) {
-    update.data = config?.initialData ?? config?.startWithValue;
-    update.status = 'success';
-    update.hasEmitted = true;
+    const initialDataValue = config?.initialData ?? config?.startWithValue;
+
+    // In suspense mode, throw errors so React Error Boundaries can catch them.
+    // In non-suspense mode, surface errors via status so consumers can handle them locally.
+    if (suspenseEnabled && update.error) {
+      throw update.error;
+    }
+
+    return {
+      ...update,
+      data: initialDataValue,
+      status: 'success',
+      hasEmitted: true,
+    } as ObservableStatus<T>;
   }
 
   // throw an error if there is an error

test/auth.test.tsx

@@ -1,6 +1,8 @@
 import { cleanup, render, waitFor, renderHook, act } from '@testing-library/react';
 import '@testing-library/jest-dom/extend-expect';
 import * as React from 'react';
+import { NEVER } from 'rxjs';
+import { preloadObservable } from '../src/useObservable';
 import {
   FirebaseAppProvider,
   AuthCheck,
@@ -326,6 +328,39 @@ describe('Authentication', () => {
       expect(result.current.data).toEqual(getAuth(app).currentUser);
     });
 
+    it('synchronously returns the current user without waiting for the observable', async () => {
+      await act(async () => {
+        await signIn();
+      });
+
+      // Replace the auth:user observable with NEVER so it never emits.
+      // Without the fix (no initialData seeding), status is 'loading' on first render.
+      // With the fix (initialData = auth.currentUser), status is 'success' synchronously.
+      const cache = (globalThis as any)._reactFirePreloadedObservables as Map<string, any>;
+      const authUserKey = `auth:user:${getAuth(app).name}`;
+      cache?.delete(authUserKey);
+      preloadObservable(NEVER, authUserKey);
+
+      let capturedFirstRender: { user: any; status: string } | undefined;
+
+      const UserComponent = () => {
+        const { data: user, status } = useUser();
+        if (capturedFirstRender === undefined) {
+          capturedFirstRender = { user, status };
+        }
+        return <span data-testid="user-output">{String(status)}</span>;
+      };
+
+      try {
+        render(<UserComponent />, { wrapper: Provider });
+
+        expect(capturedFirstRender!.status).toBe('success');
+        expect(capturedFirstRender!.user).toEqual(getAuth(app).currentUser);
+      } finally {
+        cache?.delete(authUserKey);
+      }
+    });
+
     it('does not show a logged-out user after navigating away', async () => {
       await signIn();