feat(swap-widget): hook into a host-initialized AppKit instance (#12475)

Author: kaladinlight

packages/public-api/docs/swap-widget-sdk.md

@@ -48,7 +48,7 @@ function App() {
 ## Key things to know
 
 - **Wallet connection is built in.** The widget connects wallets via Reown AppKit (EVM, Bitcoin, and Solana).
-- **AppKit must be initialized for the widget to render.** Either pass `walletConnectProjectId` and the widget initializes AppKit for you (get a free project ID at [dashboard.reown.com](https://dashboard.reown.com)), or initialize AppKit yourself in the host app and the widget reads the shared instance — pair that with `showConnectButton={false}` to drive connection from your own UI. See the [README](https://github.com/shapeshift/web/blob/develop/packages/swap-widget/README.md#wallet-connection).
+- **AppKit must be initialized before the widget mounts.** Either pass `walletConnectProjectId` and the widget initializes AppKit for you (get a free project ID at [dashboard.reown.com](https://dashboard.reown.com)), or call `createAppKit()` yourself in the host app (with a wagmi EVM adapter) before mounting the widget — the widget detects the shared singleton and supplies its own providers, so you wrap it in none. Pair the host-owned path with `showConnectButton={false}` to drive connection from your own UI. This requires `@reown/appkit*`/`wagmi`/`viem` to dedupe to a single shared copy. See the [README](https://github.com/shapeshift/web/blob/develop/packages/swap-widget/README.md#wallet-connection).
 - **`partnerCode` drives affiliate attribution.** It is forwarded to this API as the `X-Partner-Code` header. See the [Affiliate Program guide](https://github.com/shapeshift/web/blob/develop/docs/affiliates.md).
 - **Chain/asset filtering** uses the `sellFilters` and `buyFilters` props (objects with `allowedChainIds` / `disabledChainIds` / `allowedAssetIds` / `disabledAssetIds`). See the README for the full prop list and examples.
 

packages/swap-widget/README.md

@@ -91,14 +91,22 @@ and provides the `WagmiProvider` / `QueryClient` it needs — you don't wrap it
   <SwapWidget walletConnectProjectId="your-walletconnect-project-id" />
   ```
 
-- **Reuse your app's AppKit instance.** If your host app already initializes Reown AppKit, the widget
-  reads that shared instance from the AppKit singleton — omit `walletConnectProjectId` and just make
-  sure AppKit is initialized before the widget mounts. Pair this with `showConnectButton={false}` to
-  drive connection entirely from your own UI. See `src/demo/ExternalWalletApp.tsx` for a full example.
-
-The header shows a built-in **Connect** button by default; set `showConnectButton={false}` if you
-want to hide it and drive connection from your own UI (the widget still owns the underlying AppKit
-instance).
+- **Reuse your app's existing AppKit.** If your host app already calls `createAppKit()` (with a wagmi
+  EVM adapter), omit `walletConnectProjectId`. The widget detects the shared AppKit singleton, reads the
+  wagmi config off it, and provides its own `WagmiProvider` / `QueryClient` from that config — **you wrap
+  the widget in no providers of your own.** Pair this with `showConnectButton={false}` to drive
+  connection entirely from your own UI. See `src/demo/ExternalWalletApp.tsx` for a full host example.
+
+  Two requirements for this mode:
+
+  - **Initialize AppKit _before_ the widget mounts.** The widget reads the AppKit singleton when it
+    mounts and does not poll for late initialization — if AppKit isn't up yet, the widget renders nothing.
+  - **Dedupe the AppKit/wagmi packages.** `@reown/appkit*`, `wagmi`, and `viem` must resolve to a single
+    shared copy in your app, so the widget and your app share one AppKit instance and one wagmi state. A
+    duplicated copy means the widget reads an empty store and shows no connection.
+
+The header shows a built-in **Connect** button by default; set `showConnectButton={false}` to hide it
+and drive connection from your own UI.
 
 ### Supported wallet namespaces
 

packages/swap-widget/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/swap-widget",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Embeddable swap widget using ShapeShift API",
   "repository": "https://github.com/shapeshift/web",
   "license": "MIT",

packages/swap-widget/src/components/WalletProvider.tsx

@@ -1,11 +1,11 @@
 import { useAppKit } from '@reown/appkit/react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import type { ReactNode } from 'react'
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import type { Config } from 'wagmi'
 import { WagmiProvider } from 'wagmi'
 
-import { getWagmiAdapter, initializeAppKit, isAppKitInitialized } from '../config/appkit'
+import { getActiveWagmiConfig, initializeAppKit, isAppKitInitialized } from '../config/appkit'
 import { useSwapWallet } from '../contexts/SwapWalletContext'
 import { truncateAddress } from '../types'
 
@@ -17,20 +17,24 @@ type AppKitWalletProviderProps = {
 }
 
 export const AppKitWalletProvider = ({ projectId, children }: AppKitWalletProviderProps) => {
-  const [isReady, setIsReady] = useState(false)
+  // Seed from the SDK singleton so a host-initialized AppKit is picked up on the
+  // first render (no flash of null) when it was created before the widget mounts.
+  const [wagmiConfig, setWagmiConfig] = useState<Config | undefined>(() =>
+    isAppKitInitialized() ? getActiveWagmiConfig() : undefined,
+  )
 
   useEffect(() => {
-    if (projectId) initializeAppKit(projectId)
-    if (isAppKitInitialized()) setIsReady(true)
+    // Self-init only when no AppKit exists yet. If the host already called
+    // createAppKit, we hook into that shared instance rather than creating a second.
+    if (projectId && !isAppKitInitialized()) initializeAppKit(projectId)
+    if (isAppKitInitialized()) setWagmiConfig(getActiveWagmiConfig())
   }, [projectId])
 
-  const wagmiConfig = useMemo((): Config | undefined => {
-    if (!isReady) return undefined
-    return getWagmiAdapter()?.wagmiConfig as unknown as Config | undefined
-  }, [isReady])
-
   if (!wagmiConfig) return null
 
+  // We always own the WagmiProvider / QueryClient — built from the wagmi config we
+  // read off the shared AppKit singleton (whether self-init or host-owned). This is
+  // what lets a host integrate by calling createAppKit() alone, wrapping nothing.
   return (
     <WagmiProvider config={wagmiConfig}>
       <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>

packages/swap-widget/src/config/appkit.ts

@@ -16,11 +16,12 @@ import {
   polygon,
   solana,
 } from '@reown/appkit/networks'
-import { createAppKit } from '@reown/appkit/react'
+import { createAppKit, modal } from '@reown/appkit/react'
 import { BitcoinAdapter } from '@reown/appkit-adapter-bitcoin'
 import { SolanaAdapter } from '@reown/appkit-adapter-solana/react'
 import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
 import { PhantomWalletAdapter, SolflareWalletAdapter } from '@solana/wallet-adapter-wallets'
+import type { Config } from 'wagmi'
 
 const EVM_NETWORKS: readonly AppKitNetwork[] = [
   mainnet,
@@ -40,17 +41,28 @@ const EVM_NETWORKS: readonly AppKitNetwork[] = [
 
 const ALL_NETWORKS: readonly AppKitNetwork[] = [...EVM_NETWORKS, bitcoin, solana]
 
-let wagmiAdapter: WagmiAdapter | null = null
-let appKitInitialized = false
+// AppKit keeps a module-level `modal` singleton, set by `createAppKit` whether
+// it's called by this widget (self-init) or by the host app. Reading it lets the
+// widget detect — and hook into — an AppKit the host already initialized, as long
+// as `@reown/appkit*` is deduped to a single shared copy in the consumer's tree.
+export const isAppKitInitialized = (): boolean => modal !== undefined
 
-export const getWagmiAdapter = (): WagmiAdapter | null => wagmiAdapter
-
-export const isAppKitInitialized = (): boolean => appKitInitialized
+// The active wagmi Config, read off the AppKit singleton's EVM adapter. Works in
+// both modes — self-init (we registered the adapter via createAppKit) and
+// host-owned (the host's adapter). Because the widget can pull the shared config
+// from the singleton, it builds its own WagmiProvider from it — so a host only
+// needs to call `createAppKit()`, with no WagmiProvider/QueryClient wrapping.
+export const getActiveWagmiConfig = (): Config | undefined => {
+  const evmAdapter = modal?.chainAdapters?.eip155 as WagmiAdapter | undefined
+  return evmAdapter?.wagmiConfig
+}
 
 export const initializeAppKit = (projectId: string): void => {
-  if (appKitInitialized) return
+  // Already initialized — either by a previous call here, or by the host app. In
+  // the latter case we skip entirely and reuse the host's AppKit + wagmi config.
+  if (modal) return
 
-  wagmiAdapter = new WagmiAdapter({
+  const wagmiAdapter = new WagmiAdapter({
     networks: [...EVM_NETWORKS],
     projectId,
   })
@@ -68,6 +80,4 @@ export const initializeAppKit = (projectId: string): void => {
       send: false,
     },
   })
-
-  appKitInitialized = true
 }

packages/swap-widget/src/demo/ExternalWalletApp.tsx

@@ -1,10 +1,31 @@
 import './App.css'
 
-import { useAppKit, useAppKitAccount } from '@reown/appkit/react'
+import type { AppKitNetwork } from '@reown/appkit/networks'
+import {
+  arbitrum,
+  avalanche,
+  base,
+  bitcoin,
+  bsc,
+  gnosis,
+  hyperEvm,
+  katana,
+  mainnet,
+  megaeth,
+  monad,
+  optimism,
+  plasma,
+  polygon,
+  solana,
+} from '@reown/appkit/networks'
+import { createAppKit, useAppKit, useAppKitAccount } from '@reown/appkit/react'
+import { BitcoinAdapter } from '@reown/appkit-adapter-bitcoin'
+import { SolanaAdapter } from '@reown/appkit-adapter-solana/react'
+import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
+import { PhantomWalletAdapter, SolflareWalletAdapter } from '@solana/wallet-adapter-wallets'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 
 import { SwapWidget } from '../components/SwapWidget'
-import { initializeAppKit } from '../config/appkit'
 import { truncateAddress } from '../types'
 import { DemoCustomizer, useDemoTheme } from './DemoCustomizer'
 import { WidgetModal } from './WidgetModal'
@@ -180,9 +201,54 @@ const loadThemeMode = (): 'light' | 'dark' => {
   }
 }
 
+const EVM_NETWORKS: readonly AppKitNetwork[] = [
+  mainnet,
+  polygon,
+  arbitrum,
+  optimism,
+  base,
+  avalanche,
+  bsc,
+  gnosis,
+  monad,
+  megaeth,
+  hyperEvm,
+  plasma,
+  katana,
+]
+
+const ALL_NETWORKS: readonly AppKitNetwork[] = [...EVM_NETWORKS, bitcoin, solana]
+
+let appKitInitialized = false
+
+const initAppKit = (projectId: string): void => {
+  if (appKitInitialized) return
+  appKitInitialized = true
+
+  const wagmiAdapter = new WagmiAdapter({
+    networks: [...EVM_NETWORKS],
+    projectId,
+  })
+
+  const bitcoinAdapter = new BitcoinAdapter()
+  const solanaAdapter = new SolanaAdapter({
+    wallets: [new PhantomWalletAdapter(), new SolflareWalletAdapter()] as any,
+  })
+
+  createAppKit({
+    adapters: [wagmiAdapter, bitcoinAdapter, solanaAdapter],
+    projectId,
+    networks: [...ALL_NETWORKS] as [AppKitNetwork, ...AppKitNetwork[]],
+    features: {
+      send: false,
+    },
+  })
+}
+
 export const ExternalWalletApp = () => {
   const [theme, setTheme] = useState<'light' | 'dark'>(loadThemeMode)
-  const [isReady, setIsReady] = useState(false)
+
+  useState(() => initAppKit(PROJECT_ID))
 
   useEffect(() => {
     try {
@@ -192,11 +258,5 @@ export const ExternalWalletApp = () => {
     }
   }, [theme])
 
-  useEffect(() => {
-    initializeAppKit(PROJECT_ID)
-    setIsReady(true)
-  }, [])
-
-  if (!isReady) return null
   return <ExternalDemoBody theme={theme} setTheme={setTheme} />
 }