@reown/appkit-react-native 0.0.0-chore-types-20250804204153 → 0.0.0-chore-added-import-20251002170458

package/lib/commonjs/AppKit.js

@@ -5,13 +5,18 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.AppKit = void 0;
 exports.createAppKit = createAppKit;
+var _utils = require("valtio/utils");
 var _appkitCoreReactNative = require("@reown/appkit-core-react-native");
 var _appkitCommonReactNative = require("@reown/appkit-common-react-native");
-var _appkitSiweReactNative = require("@reown/appkit-siwe-react-native");
 var _WalletConnectConnector = require("./connectors/WalletConnectConnector");
 var _HelpersUtil = require("./utils/HelpersUtil");
 var _NetworkUtil = require("./utils/NetworkUtil");
 var _RouterUtil = require("./utils/RouterUtil");
+var _SIWXUtil = require("./utils/SIWXUtil");
+const APPKIT_INSTANCE_KEY = Symbol.for('__REOWN_APPKIT_INSTANCE__');
+
+// Type helper to access the symbol-keyed property on globalThis
+
 class AppKit {
   constructor(config) {
     this.projectId = config.projectId;
@@ -44,6 +49,7 @@ class AppKit {
     this.extraConnectors = config.extraConnectors || [];
     this.initControllers(config);
     this.initConnectors();
+    this.watchBalance();
   }
 
   /**
@@ -51,20 +57,25 @@ class AppKit {
    * @param type - The type of connector to use.
    * @param options - Optional connection options.
    */
-  async connect(type, options) {
+  async connect(options) {
     try {
       const {
-        namespaces,
-        defaultChain,
-        universalLink
+        wallet,
+        walletId
       } = options ?? {};
-      const connector = await this.createConnector(type);
-      const chain = defaultChain ?? _NetworkUtil.NetworkUtil.getDefaultChainId(this.namespaces, _appkitCoreReactNative.OptionsController.state.defaultNetwork);
+      let targetWallet;
+      if (walletId) {
+        targetWallet = _appkitCoreReactNative.WalletUtil.getWallet(walletId);
+      } else if (wallet) {
+        targetWallet = wallet;
+      }
+      const connectorType = _HelpersUtil.WcHelpersUtil.getConnectorTypeByWallet(targetWallet);
+      const connector = await this.createConnector(connectorType);
+      const chain = _NetworkUtil.NetworkUtil.getDefaultNetwork(this.namespaces, _appkitCoreReactNative.OptionsController.state.defaultNetwork);
       const approvedNamespaces = await connector.connect({
-        namespaces: namespaces ?? this.namespaces,
-        defaultChain: chain,
-        universalLink,
-        siweConfig: this.config?.siweConfig
+        namespaces: this.namespaces,
+        defaultNetwork: chain,
+        universalLink: targetWallet?.link_mode ?? undefined
       });
       this.processConnection(connector, approvedNamespaces);
 
@@ -76,11 +87,11 @@ class AppKit {
         });
       }
     } catch (error) {
-      console.warn('Connection failed:', error);
+      _appkitCoreReactNative.LogController.sendError(error, 'AppKit.ts', 'connect');
       throw error;
     }
   }
-  processConnection(connector, namespaces, shouldCloseModal = true) {
+  async processConnection(connector, namespaces) {
     if (!namespaces || Object.keys(namespaces).length === 0) {
       throw new Error('No namespaces provided');
     }
@@ -96,19 +107,11 @@ class AppKit {
     this.setConnection(initializedAdapters, namespaces, walletInfo, properties);
 
     // Sync accounts
-    this.syncAccounts(initializedAdapters);
-
-    // Handle SIWE if enabled
-    this.handleSiweConnectionIfEnabled(shouldCloseModal);
-  }
-  handleSiweConnectionIfEnabled(shouldCloseModal = true) {
-    if (_appkitCoreReactNative.OptionsController.state.isSiweEnabled && _appkitCoreReactNative.ConnectionsController.state.activeNamespace === 'eip155') {
-      this.handleSiweChange({
-        isConnection: true
-      });
-    } else if (shouldCloseModal) {
-      _appkitCoreReactNative.ModalController.close();
-    }
+    await this.syncAccounts(initializedAdapters);
+    await _SIWXUtil.SIWXUtil.initializeIfEnabled({
+      onDisconnect: this.disconnect,
+      closeModal: true
+    });
   }
 
   /**
@@ -138,14 +141,18 @@ class AppKit {
       if (_appkitCoreReactNative.ConnectionsController.state.activeNamespace === undefined) {
         _appkitCoreReactNative.ConnectionsController.setActiveNamespace(_appkitCoreReactNative.OptionsController.state.defaultNetwork?.chainNamespace);
       }
-      if (_appkitCoreReactNative.OptionsController.state.isSiweEnabled) {
-        await _appkitSiweReactNative.SIWEController.signOut();
+      if (_SIWXUtil.SIWXUtil.getSIWX()?.signOutOnDisconnect) {
+        await _SIWXUtil.SIWXUtil.clearSessions();
       }
       _appkitCoreReactNative.EventsController.sendEvent({
         type: 'track',
-        event: 'DISCONNECT_SUCCESS'
+        event: 'DISCONNECT_SUCCESS',
+        properties: {
+          namespace: activeNamespace
+        }
       });
     } catch (error) {
+      _appkitCoreReactNative.LogController.sendError(error, 'AppKit.ts', 'disconnect');
       _appkitCoreReactNative.EventsController.sendEvent({
         type: 'track',
         event: 'DISCONNECT_ERROR'
@@ -183,25 +190,26 @@ class AppKit {
       type: 'track',
       event: 'SWITCH_NETWORK',
       properties: {
-        network: network.id
+        network: network.caipNetworkId
       }
     });
     _appkitCoreReactNative.ConnectionsController.setActiveNetwork(network.chainNamespace, network.caipNetworkId);
-    if (_appkitCoreReactNative.ConnectionsController.state.activeNamespace !== network.chainNamespace) {
-      _appkitCoreReactNative.ConnectionsController.setActiveNamespace(network.chainNamespace);
-    }
   }
   open(options) {
     _appkitCoreReactNative.ModalController.open(options);
   }
   async close() {
     _appkitCoreReactNative.ModalController.close();
-    if (_appkitCoreReactNative.OptionsController.state.isSiweEnabled && _appkitCoreReactNative.ConnectionsController.state.isConnected) {
-      const session = await _appkitSiweReactNative.SIWEController.getSession();
-      if (!session && _appkitSiweReactNative.SIWEController.state.status !== 'success' && _appkitCoreReactNative.ConnectionsController.state.activeNamespace === 'eip155' && !!_appkitCoreReactNative.ConnectionsController.state.activeAddress) {
-        await this.disconnect();
+    const isSIWXRequired = _SIWXUtil.SIWXUtil.getSIWX()?.getRequired?.();
+    if (isSIWXRequired && _appkitCoreReactNative.ConnectionsController.state.isConnected) {
+      const sessions = await _SIWXUtil.SIWXUtil.getSessions();
+      if (!sessions.length) {
+        return await this.disconnect();
       }
     }
+    if (_appkitCoreReactNative.RouterController.state.view === 'UnsupportedChain') {
+      return await this.disconnect();
+    }
     _RouterUtil.RouterUtil.checkOnRampBack();
     _RouterUtil.RouterUtil.checkSocialLoginBack();
   }
@@ -210,18 +218,28 @@ class AppKit {
       _RouterUtil.RouterUtil.checkBack();
       return _appkitCoreReactNative.RouterController.goBack();
     }
+    const isSIWXRequired = _SIWXUtil.SIWXUtil.getSIWX()?.getRequired?.();
+    if (isSIWXRequired) {
+      // Don't close the modal if SIWX is required
+      return;
+    }
     return this.close();
   }
   async switchAccountType(namespace, type, network) {
     const adapter = this.getAdapterByNamespace(namespace);
     if (!adapter) throw new Error('No active adapter');
-    _appkitCoreReactNative.ConnectionsController.setAccountType(namespace, type);
+    const address = _appkitCoreReactNative.ConnectionsController.setAccountType(namespace, type);
 
     // Get balances from API
     _appkitCoreReactNative.ConnectionsController.fetchBalance();
 
+    // Fetch transactions for the new account
+    if (address) {
+      _appkitCoreReactNative.TransactionsController.fetchTransactions(address, true);
+    }
+
     // Sync balances from adapter
-    this.syncBalances(adapter, network);
+    this.syncNativeBalance(adapter, network);
     _appkitCoreReactNative.EventsController.sendEvent({
       type: 'track',
       event: 'SET_PREFERRED_ACCOUNT_TYPE',
@@ -264,22 +282,39 @@ class AppKit {
    * This attempts to restore previous sessions.
    */
   async initConnectors() {
+    _appkitCoreReactNative.ModalController.setLoading(true);
+
+    //Always init the walletconnect connector
+    await this.createWalletConnectConnector();
     const connectedConnectors = await _appkitCoreReactNative.StorageUtil.getConnectedConnectors();
     if (connectedConnectors.length > 0) {
-      _appkitCoreReactNative.ModalController.setLoading(true);
       for (const connected of connectedConnectors) {
         try {
           const connector = await this.createConnector(connected.type);
           const namespaces = connector.getNamespaces();
-          this.processConnection(connector, namespaces, false);
+          await this.processConnection(connector, namespaces);
         } catch (error) {
-          // Use console.warn for non-critical initialization failures
-          console.warn(`Failed to initialize connector type ${connected.type}:`, error);
+          _appkitCoreReactNative.LogController.sendError(error, 'AppKit.ts', 'initializeConnector', {
+            connectorType: connected.type
+          });
           await _appkitCoreReactNative.StorageUtil.removeConnectedConnectors(connected.type);
         }
       }
-      _appkitCoreReactNative.ModalController.setLoading(false);
+      const address = _appkitCoreReactNative.ConnectionsController.state.activeAddress;
+      const walletInfo = _appkitCoreReactNative.ConnectionsController.state.walletInfo;
+      if (address) {
+        _appkitCoreReactNative.EventsController.sendEvent({
+          type: 'track',
+          event: 'CONNECT_SUCCESS',
+          address: _appkitCoreReactNative.CoreHelperUtil.getPlainAddress(address),
+          properties: {
+            name: walletInfo?.name ?? 'Unknown',
+            reconnect: true
+          }
+        });
+      }
     }
+    _appkitCoreReactNative.ModalController.setLoading(false);
   }
   setupAdaptersAndSubscribe(connector, namespaces) {
     const adapters = this.adapters.filter(adapter => namespaces.includes(adapter.getSupportedNamespace()));
@@ -308,11 +343,11 @@ class AppKit {
       const namespace = adapter.getSupportedNamespace();
       const connection = _appkitCoreReactNative.ConnectionsController.state.connections.get(namespace);
       const network = this.networks.find(n => n.id?.toString() === connection?.caipNetwork?.split(':')[1]);
-      this.syncBalances(adapter, network);
+      this.syncNativeBalance(adapter, network);
       this.syncIdentity(namespace, connection);
     });
   }
-  syncBalances(adapter, network) {
+  syncNativeBalance(adapter, network) {
     if (adapter && network) {
       const accounts = adapter.getAccounts();
       if (accounts && accounts.length > 0) {
@@ -348,10 +383,57 @@ class AppKit {
           _appkitCoreReactNative.ConnectionsController.updateIdentity(namespace, connection, plainAddress, identity);
         }
       } catch (error) {
+        _appkitCoreReactNative.LogController.sendError(error, 'AppKit.ts', 'syncIdentity');
         // Continue processing other addresses even if one fails
       }
     }
   }
+  refreshBalance(fetchAllBalances = false) {
+    try {
+      if (fetchAllBalances) {
+        _appkitCoreReactNative.ConnectionsController.fetchBalance();
+      }
+      const ns = _appkitCoreReactNative.ConnectionsController.state.activeNamespace;
+      const network = _appkitCoreReactNative.ConnectionsController.state.activeNetwork;
+      if (ns && network) {
+        const adapter = this.getAdapterByNamespace(ns);
+        if (adapter) {
+          this.syncNativeBalance(adapter, network);
+        }
+      }
+    } catch (error) {
+      // ignore
+      _appkitCoreReactNative.LogController.sendError(error, 'AppKit.ts', 'refreshBalance');
+    }
+  }
+  startBalancePolling(fetchAllBalances = false) {
+    if (this.balanceIntervalId) return;
+    // immediate fetch
+    this.refreshBalance(fetchAllBalances);
+    this.balanceIntervalId = setInterval(() => this.refreshBalance(fetchAllBalances), 10000);
+  }
+  stopBalancePolling() {
+    if (this.balanceIntervalId) {
+      clearInterval(this.balanceIntervalId);
+      this.balanceIntervalId = undefined;
+    }
+  }
+  watchBalance() {
+    // watch balance when user is on account or account default view
+    const recomputePolling = () => {
+      const open = _appkitCoreReactNative.ModalController.state.open;
+      const view = _appkitCoreReactNative.RouterController.state.view;
+      if (open && (view === 'Account' || view === 'AccountDefault')) {
+        // fetch all balances when user is using embedded wallet
+        this.startBalancePolling(view === 'Account');
+      } else {
+        this.stopBalancePolling();
+      }
+    };
+    recomputePolling();
+    (0, _utils.subscribeKey)(_appkitCoreReactNative.RouterController.state, 'view', () => recomputePolling());
+    (0, _utils.subscribeKey)(_appkitCoreReactNative.ModalController.state, 'open', () => recomputePolling());
+  }
   setConnection(adapters, approvedNamespaces, wallet, properties) {
     adapters.forEach(async adapter => {
       const namespace = adapter.getSupportedNamespace();
@@ -362,7 +444,8 @@ class AppKit {
       const caipNetwork = adapter?.connector?.getChainId(namespace);
       const namespaceProperties = {
         ...properties,
-        smartAccounts: properties?.smartAccounts?.filter(account => account.startsWith(namespace))
+        smartAccounts: properties?.smartAccounts?.filter(account => account.startsWith(namespace)),
+        canAddEvmChain: wallet?.name === 'MetaMask Wallet' // MetaMask allows adding EVM chains after connecting
       };
       _appkitCoreReactNative.ConnectionsController.setConnection({
         accounts,
@@ -386,33 +469,42 @@ class AppKit {
     }) => {
       const namespace = adapter.getSupportedNamespace();
       _appkitCoreReactNative.ConnectionsController.updateAccounts(namespace, accounts);
-      if (namespace === 'eip155') {
-        this.handleSiweChange({
-          isAccountChange: true
-        });
-      }
     });
-    adapter.on('chainChanged', ({
+    adapter.on('chainChanged', async ({
       chainId
     }) => {
-      //eslint-disable-next-line no-console
-      console.log('chainChanged', chainId);
+      const isSupported = this.networks.some(network => network.id?.toString() === chainId);
+      if (!isSupported) {
+        return this.navigate('UnsupportedChain');
+      }
       const namespace = adapter.getSupportedNamespace();
       const chain = `${namespace}:${chainId}`;
+      const activeNetwork = _appkitCoreReactNative.ConnectionsController.getActiveNetworkId(namespace);
+      if (activeNetwork === chain) {
+        // No need to update the active network
+        return;
+      }
       _appkitCoreReactNative.ConnectionsController.setActiveNetwork(namespace, chain);
       const connection = _appkitCoreReactNative.ConnectionsController.state.connections.get(namespace);
       const isAuth = !!connection?.properties?.provider;
       const network = this.networks.find(n => n.id?.toString() === chainId);
-      this.syncBalances(adapter, network);
+      this.syncNativeBalance(adapter, network);
       _appkitCoreReactNative.SendController.resetState();
+
+      // Refresh balance for embedded wallets
       if (isAuth) {
         _appkitCoreReactNative.ConnectionsController.fetchBalance();
       }
-      if (namespace === 'eip155') {
-        this.handleSiweChange({
-          isNetworkChange: true
-        });
+      const address = connection?.accounts?.find(account => account.startsWith(`${namespace}:${chainId}`));
+      if (address) {
+        _appkitCoreReactNative.TransactionsController.fetchTransactions(address, true);
       }
+      const closeModal = _appkitCoreReactNative.RouterController.state.view === 'UnsupportedChain';
+      _SIWXUtil.SIWXUtil.initializeIfEnabled({
+        onDisconnect: this.disconnect,
+        caipAddress: address,
+        closeModal
+      });
     });
     adapter.on('disconnect', () => {
       const namespace = adapter.getSupportedNamespace();
@@ -422,14 +514,13 @@ class AppKit {
       address,
       balance
     }) => {
-      //eslint-disable-next-line no-console
-      console.log('balanceChanged', address, balance);
       const namespace = adapter.getSupportedNamespace();
       _appkitCoreReactNative.ConnectionsController.updateBalance(namespace, address, balance);
     });
   }
   async initControllers(options) {
     await this.initStorageAndValues(options);
+    let defaultNetwork;
     _appkitCoreReactNative.OptionsController.setProjectId(options.projectId);
     _appkitCoreReactNative.OptionsController.setMetadata(options.metadata);
     _appkitCoreReactNative.OptionsController.setIncludeWalletIds(options.includeWalletIds);
@@ -437,25 +528,52 @@ class AppKit {
     this.setCustomWallets(options);
     _appkitCoreReactNative.OptionsController.setFeaturedWalletIds(options.featuredWalletIds);
     _appkitCoreReactNative.OptionsController.setEnableAnalytics(options.enableAnalytics);
-    _appkitCoreReactNative.OptionsController.setDebug(options.debug);
+    _appkitCoreReactNative.OptionsController.setDebug(options.debug && __DEV__);
+
+    // Initialize LogController after debug option is set
+    _appkitCoreReactNative.LogController.initialize();
+    _appkitCoreReactNative.LogController.sendInfo('AppKit initialization started', 'AppKit.ts', 'initControllers', {
+      projectId: options.projectId,
+      adapters: this.adapters.map(a => a.constructor.name),
+      networks: this.networks.map(n => n.name),
+      debug: options.debug
+    });
     _appkitCoreReactNative.OptionsController.setFeatures(options.features);
+    _appkitCoreReactNative.OptionsController.setRequestedNetworks(this.networks);
     if (options.defaultNetwork) {
-      const network = _NetworkUtil.NetworkUtil.formatNetwork(options.defaultNetwork, this.projectId);
-      _appkitCoreReactNative.OptionsController.setDefaultNetwork(network);
+      defaultNetwork = _NetworkUtil.NetworkUtil.formatNetwork(options.defaultNetwork, this.projectId);
+      _appkitCoreReactNative.OptionsController.setDefaultNetwork(defaultNetwork);
     }
-    _appkitCoreReactNative.ThemeController.setThemeMode(options.themeMode);
+    _appkitCoreReactNative.ThemeController.setDefaultThemeMode(options.themeMode);
     _appkitCoreReactNative.ThemeController.setThemeVariables(options.themeVariables);
     _appkitCoreReactNative.OptionsController.setSdkVersion(_appkitCoreReactNative.CoreHelperUtil.generateSdkVersion(this.adapters, _appkitCommonReactNative.ConstantsUtil.VERSION));
     if (options.clipboardClient) {
       _appkitCoreReactNative.OptionsController.setClipboardClient(options.clipboardClient);
     }
     _appkitCoreReactNative.ConnectionsController.setNetworks(this.networks);
-    if (options.siweConfig) {
-      _appkitSiweReactNative.SIWEController.setSIWEClient(options.siweConfig);
+    if (options.siwx) {
+      _appkitCoreReactNative.OptionsController.setSiwx(options.siwx);
     }
     if ((options.features?.onramp === true || options.features?.onramp === undefined) && (options.metadata?.redirect?.universal || options.metadata?.redirect?.native)) {
       _appkitCoreReactNative.OptionsController.setIsOnRampEnabled(true);
     }
+    _appkitCoreReactNative.EventsController.sendEvent({
+      type: 'track',
+      event: 'INITIALIZE',
+      properties: {
+        showWallets: options.features?.showWallets,
+        themeMode: options.themeMode,
+        themeVariables: options.themeVariables,
+        networks: this.networks.map(network => network.caipNetworkId).filter(Boolean),
+        defaultNetwork: defaultNetwork?.caipNetworkId,
+        metadata: options.metadata,
+        enableAnalytics: options.enableAnalytics,
+        features: options.features,
+        adapters: this.adapters.map(adapter => adapter?.constructor?.name).filter(Boolean),
+        extraConnectors: this.extraConnectors.map(connector => connector?.type).filter(Boolean),
+        siwx: !!options.siwx
+      }
+    });
   }
   async initActiveNamespace() {
     const activeNamespace = await _appkitCoreReactNative.StorageUtil.getActiveNamespace();
@@ -472,13 +590,13 @@ class AppKit {
         includeWalletIds,
         excludeWalletIds
       } = options;
-      if (includeWalletIds) {
+      if (includeWalletIds?.length) {
         return includeWalletIds.includes(wallet.id);
       }
-      if (excludeWalletIds) {
+      if (excludeWalletIds?.length) {
         return !excludeWalletIds.includes(wallet.id);
       }
-      return true;
+      return this.networks.some(network => wallet.chains?.some(chain => network.caipNetworkId === chain));
     });
     _appkitCoreReactNative.WcController.setRecentWallets(filteredWallets);
   }
@@ -499,10 +617,15 @@ class AppKit {
       adapters
     } = options;
     const customList = [...(customWallets ?? [])];
-    const addPhantom = adapters.some(adapter => adapter.getSupportedNamespace() === 'solana') && extraConnectors?.some(connector => connector.type.toLowerCase() === 'phantom') && !customList.some(wallet => wallet.id === _appkitCommonReactNative.ConstantsUtil.PHANTOM_CUSTOM_WALLET.id);
+    const isSolanaEnabled = adapters.some(adapter => adapter.getSupportedNamespace() === 'solana') && this.networks.some(network => network.chainNamespace === 'solana');
+    const addPhantom = isSolanaEnabled && extraConnectors?.some(connector => connector.type.toLowerCase() === 'phantom') && !customList.some(wallet => wallet.id === _appkitCommonReactNative.ConstantsUtil.PHANTOM_CUSTOM_WALLET.id);
     if (addPhantom) {
       customList.push(_appkitCommonReactNative.ConstantsUtil.PHANTOM_CUSTOM_WALLET);
     }
+    const addSolflare = isSolanaEnabled && extraConnectors?.some(connector => connector.type.toLowerCase() === 'solflare') && !customList.some(wallet => wallet.id === _appkitCommonReactNative.ConstantsUtil.SOLFLARE_CUSTOM_WALLET.id);
+    if (addSolflare) {
+      customList.push(_appkitCommonReactNative.ConstantsUtil.SOLFLARE_CUSTOM_WALLET);
+    }
     _appkitCoreReactNative.OptionsController.setCustomWallets(customList);
   }
   async initStorageAndValues(options) {
@@ -513,52 +636,54 @@ class AppKit {
     await this.initActiveNamespace();
     await this.initRecentWallets(options);
   }
-  onSiweNavigation = () => {
+  navigate = routeName => {
+    if (_appkitCoreReactNative.RouterController.state.view === routeName) {
+      return;
+    }
     if (_appkitCoreReactNative.ModalController.state.open) {
-      _appkitCoreReactNative.RouterController.push('ConnectingSiwe');
+      _appkitCoreReactNative.RouterController.push(routeName);
     } else {
       _appkitCoreReactNative.ModalController.open({
-        view: 'ConnectingSiwe'
+        view: routeName
       });
     }
   };
-  async handleSiweChange(params) {
-    const {
-      isNetworkChange,
-      isAccountChange,
-      isConnection
-    } = params ?? {};
-    const {
-      enabled,
-      signOutOnAccountChange,
-      signOutOnNetworkChange
-    } = _appkitSiweReactNative.SIWEController.state._client?.options ?? {};
-    if (enabled) {
-      const session = await _appkitSiweReactNative.SIWEController.getSession();
-      if (session && isAccountChange) {
-        if (signOutOnAccountChange) {
-          // If the address has changed and signOnAccountChange is enabled, sign out
-          await _appkitSiweReactNative.SIWEController.signOut();
-          return this.onSiweNavigation();
-        }
-      } else if (isNetworkChange) {
-        if (signOutOnNetworkChange) {
-          // If the network has changed and signOnNetworkChange is enabled, sign out
-          await _appkitSiweReactNative.SIWEController.signOut();
-          return this.onSiweNavigation();
-        }
-      } else if (!session) {
-        // If it's connected but there's no session, show sign view
-        return this.onSiweNavigation();
-      } else if (isConnection) {
-        // Connected with 1CA
-        _appkitCoreReactNative.ModalController.close();
-      }
-    }
-  }
 }
+
+/**
+ * Creates or returns the existing AppKit singleton instance.
+ *
+ * @warning This function implements a singleton pattern. If an instance already exists,
+ * it will be returned and the provided config parameter will be IGNORED. If you need to
+ * change configuration, you must reload your application or clear the singleton manually.
+ *
+ * @param config - AppKit configuration options
+ * @returns The AppKit singleton instance
+ * @throws Error if configuration validation fails
+ */
 exports.AppKit = AppKit;
 function createAppKit(config) {
-  return new AppKit(config);
+  try {
+    const globalWithAppKit = globalThis;
+    if (!globalWithAppKit[APPKIT_INSTANCE_KEY]) {
+      if (config.debug && __DEV__) {
+        // using console.log to avoid possible issues with LogController not being initialized
+        //eslint-disable-next-line no-console
+        console.log('AppKit: Creating new instance - AppKit.ts:createAppKit');
+      }
+      globalWithAppKit[APPKIT_INSTANCE_KEY] = new AppKit(config);
+    } else if (config.debug && __DEV__) {
+      //eslint-disable-next-line no-console
+      console.log('AppKit: Reusing existing instance - AppKit.ts:createAppKit');
+    }
+    return globalWithAppKit[APPKIT_INSTANCE_KEY];
+  } catch (error) {
+    if (__DEV__) {
+      // using console.error to avoid possible issues with LogController not being initialized
+      //eslint-disable-next-line no-console
+      console.error('AppKit: Failed to create instance - AppKit.ts:createAppKit', error);
+    }
+    throw error;
+  }
 }
 //# sourceMappingURL=AppKit.js.map