fix(wallet-adapter-react): support async autoConnect prop values

Author: 0xmaayan

.changeset/async-autoconnect-fix.md

@@ -0,0 +1,10 @@
+---
+"@aptos-labs/wallet-adapter-react": patch
+---
+
+fix: support async autoConnect prop values
+
+Previously, if `autoConnect` started as `false` and later became `true` (e.g., after fetching user preferences from an API), the auto-connect would never trigger because the attempt was marked as "done" on the first render.
+
+Now, the auto-connect attempt is only marked as complete when `autoConnect` is actually truthy, allowing dApps to set `autoConnect` asynchronously.
+

apps/nextjs-example/src/components/AutoConnectProvider.tsx

@@ -6,6 +6,7 @@ import {
   createContext,
   useContext,
   useEffect,
+  useRef,
   useState,
 } from "react";
 
@@ -28,22 +29,29 @@ export const AutoConnectProvider: FC<{ children: ReactNode }> = ({
   children,
 }) => {
   const [autoConnect, setAutoConnect] = useState(false);
+  // Track if we've read from localStorage to avoid deleting it on initial mount
+  const hasInitializedRef = useRef(false);
 
   useEffect(() => {
     // Wait until the app hydrates before populating `autoConnect` from local storage
     try {
       const isAutoConnect = localStorage.getItem(
         AUTO_CONNECT_LOCAL_STORAGE_KEY,
       );
+      hasInitializedRef.current = true;
       if (isAutoConnect) return setAutoConnect(JSON.parse(isAutoConnect));
     } catch (e) {
+      hasInitializedRef.current = true;
       if (typeof window !== "undefined") {
         console.error(e);
       }
     }
   }, []);
 
   useEffect(() => {
+    // Don't write to localStorage until we've read the initial value
+    if (!hasInitializedRef.current) return;
+
     try {
       if (!autoConnect) {
         localStorage.removeItem(AUTO_CONNECT_LOCAL_STORAGE_KEY);

apps/nextjs-x-chain/src/components/AutoConnectProvider.tsx

@@ -6,6 +6,7 @@ import {
   createContext,
   useContext,
   useEffect,
+  useRef,
   useState,
 } from "react";
 
@@ -28,22 +29,29 @@ export const AutoConnectProvider: FC<{ children: ReactNode }> = ({
   children,
 }) => {
   const [autoConnect, setAutoConnect] = useState(false);
+  // Track if we've read from localStorage to avoid deleting it on initial mount
+  const hasInitializedRef = useRef(false);
 
   useEffect(() => {
     // Wait until the app hydrates before populating `autoConnect` from local storage
     try {
       const isAutoConnect = localStorage.getItem(
         AUTO_CONNECT_LOCAL_STORAGE_KEY,
       );
+      hasInitializedRef.current = true;
       if (isAutoConnect) return setAutoConnect(JSON.parse(isAutoConnect));
     } catch (e) {
+      hasInitializedRef.current = true;
       if (typeof window !== "undefined") {
         console.error(e);
       }
     }
   }, []);
 
   useEffect(() => {
+    // Don't write to localStorage until we've read the initial value
+    if (!hasInitializedRef.current) return;
+
     try {
       if (!autoConnect) {
         localStorage.removeItem(AUTO_CONNECT_LOCAL_STORAGE_KEY);

packages/wallet-adapter-react/src/WalletProvider.tsx

@@ -94,14 +94,17 @@ export const AptosWalletAdapterProvider: FC<AptosWalletProviderProps> = ({
     if (didAttemptAutoConnectRef.current || !walletCore?.wallets.length) {
       return;
     }
-    didAttemptAutoConnectRef.current = true;
 
-    // If auto connect is not set or is false, ignore the attempt
+    // If auto connect is not set or is false, don't mark as attempted yet
+    // This allows retry when autoConnect becomes true asynchronously
     if (!autoConnect) {
       setIsLoading(false);
       return;
     }
 
+    // Only mark as attempted when autoConnect is truthy
+    didAttemptAutoConnectRef.current = true;
+
     // Make sure the user has a previously connected wallet
     const walletName = localStorage.getItem("AptosWalletName");
     if (!walletName) {

packages/wallet-adapter-react/tests/WalletProvider.test.tsx

@@ -178,6 +178,89 @@ describe("AptosWalletAdapterProvider", () => {
 
       expect(mockWalletCore.connect).not.toHaveBeenCalled();
     });
+
+    it("should auto-connect when autoConnect changes from false to true asynchronously", async () => {
+      // Store a wallet name to enable auto-connect
+      localStorage.setItem("AptosWalletName", "TestWallet");
+
+      // Component that simulates async autoConnect prop
+      function AsyncAutoConnectWrapper() {
+        const [autoConnect, setAutoConnect] = React.useState(false);
+
+        React.useEffect(() => {
+          // Simulate async operation (e.g., fetching user preferences)
+          const timer = setTimeout(() => {
+            setAutoConnect(true);
+          }, 50);
+          return () => clearTimeout(timer);
+        }, []);
+
+        return (
+          <AptosWalletAdapterProvider autoConnect={autoConnect} disableTelemetry>
+            <TestConsumer />
+          </AptosWalletAdapterProvider>
+        );
+      }
+
+      render(<AsyncAutoConnectWrapper />);
+
+      // Initially, connect should not have been called
+      expect(mockWalletCore.connect).not.toHaveBeenCalled();
+
+      // Wait for autoConnect to become true and trigger connect
+      await waitFor(
+        () => {
+          expect(mockWalletCore.connect).toHaveBeenCalledWith("TestWallet");
+        },
+        { timeout: 3000 }
+      );
+    });
+
+    it("should only attempt auto-connect once when autoConnect becomes true", async () => {
+      localStorage.setItem("AptosWalletName", "TestWallet");
+
+      function MultipleUpdateWrapper() {
+        const [autoConnect, setAutoConnect] = React.useState(false);
+        const [, forceUpdate] = React.useState(0);
+
+        React.useEffect(() => {
+          // Set autoConnect to true
+          const timer1 = setTimeout(() => setAutoConnect(true), 30);
+          // Trigger additional re-renders after autoConnect is true
+          const timer2 = setTimeout(() => forceUpdate((n) => n + 1), 80);
+          const timer3 = setTimeout(() => forceUpdate((n) => n + 1), 130);
+          return () => {
+            clearTimeout(timer1);
+            clearTimeout(timer2);
+            clearTimeout(timer3);
+          };
+        }, []);
+
+        return (
+          <AptosWalletAdapterProvider autoConnect={autoConnect} disableTelemetry>
+            <TestConsumer />
+          </AptosWalletAdapterProvider>
+        );
+      }
+
+      render(<MultipleUpdateWrapper />);
+
+      // Wait for auto-connect to be called
+      await waitFor(
+        () => {
+          expect(mockWalletCore.connect).toHaveBeenCalled();
+        },
+        { timeout: 3000 }
+      );
+
+      // Wait for additional re-renders to complete
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      });
+
+      // Should only be called once
+      expect(mockWalletCore.connect).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe("event handlers", () => {