feat: add ConfigContext infrastructure for instance-scoped configuration

Introduces React Context pattern for config access, enabling future support
for multiple WormholeConnect instances on the same page.

Changes:
- Add ConfigContext with ConfigProvider and useConfig() hook
- Wrap WormholeConnect with ConfigProvider
- Update AppRouter to use useConfig() (example migration)
- Add TestConfigContext pattern in testHelpers for test isolation
- Mark singleton export with @deprecated JSDoc
- Fix TypeScript dev server errors (@types/color, env.d.ts)

The singleton remains functional for backwards compatibility.
Migration can proceed incrementally file-by-file.

Author: DBosley

package-lock.json

@@ -154,6 +154,7 @@
     "@playwright/test": "1.54.1",
     "@testing-library/jest-dom": "^6.8.0",
     "@testing-library/react": "^16.3.0",
+    "@types/color": "^4.2.0",
     "@types/node": "^20",
     "@types/node-fetch": "^2.6.3",
     "@types/react": "^19.1.4",

package.json

@@ -1,15 +1,13 @@
-import React, { useCallback, useContext, useEffect, useRef } from 'react';
+import React, { useContext, useEffect, useRef } from 'react';
 import { useDispatch, useSelector } from 'react-redux';
 import { useTheme } from '@mui/material/styles';
 
 import './App.css';
 import type { RootState } from './store';
 import { clearRedeem } from './store/redeem';
 import { clearTransfer } from './store/transferInput';
-import { isEmptyObject, usePrevious } from './utils';
-import type { WormholeConnectConfig } from './config/types';
-import { setConfig } from './config';
-import config from './config';
+import { usePrevious } from './utils';
+import { useConfig } from './contexts/ConfigContext';
 
 import Terms from './views/Terms';
 import TxSearch from './views/TxSearch';
@@ -80,56 +78,32 @@ const AppRouterContent = () => {
   );
 };
 
-interface Props {
-  config?: WormholeConnectConfig;
-}
-
 // since this will be embedded, we'll have to use pseudo routes instead of relying on the url
-function AppRouter(props: Props) {
+function AppRouter() {
   const dispatch = useDispatch();
-
-  const hasSetSsgConfig = useRef(false);
-  const isInitialLoad = useRef(true);
+  const config = useConfig();
   const route = useSelector((state: RootState) => state.router.route);
 
-  const loadConfig = useCallback((customConfig: WormholeConnectConfig) => {
-    if (!isEmptyObject(customConfig)) {
-      setConfig(customConfig);
-    }
-
-    hasSetSsgConfig.current = true;
-    config.triggerEvent({
-      type: 'config',
-      config: customConfig,
-    });
-  }, []);
+  // Track config changes to clear transfer state when config is updated
+  const prevConfig = usePrevious(config);
+  const hasInitialized = useRef(false);
 
-  if (!hasSetSsgConfig.current) {
-    // This runs once in SSG step (server-side pre-rendering)
-    if (props.config) {
-      loadConfig(props.config);
-    }
-    if (route !== 'bridge') {
-      // The route may not be bridge on initial load if the component was re-rendered after client side navigation
-      dispatch(setRoute('bridge'));
+  // SSG route initialization - ensure we start on bridge route
+  useEffect(() => {
+    if (!hasInitialized.current) {
+      hasInitialized.current = true;
+      if (route !== 'bridge') {
+        dispatch(setRoute('bridge'));
+      }
     }
-  }
+  }, [route, dispatch]);
 
+  // Clear transfer state when config changes (after initial load)
   useEffect(() => {
-    if (isInitialLoad.current) {
-      isInitialLoad.current = false;
-      config.triggerEvent({
-        type: 'load',
-        config: props.config,
-      });
-    } else {
-      if (props.config) {
-        loadConfig(props.config);
-        dispatch(clearTransfer());
-      }
+    if (prevConfig && prevConfig !== config) {
+      dispatch(clearTransfer());
     }
-  }, [props.config, loadConfig, dispatch]);
-  // END config loading code
+  }, [config, prevConfig, dispatch]);
 
   return <AppRouterContent />;
 }

src/AppRouter.tsx

@@ -12,6 +12,7 @@ import type { WormholeConnectTheme } from 'theme';
 import { RouteProvider } from './contexts/RouteContext';
 import { TokensProvider } from './contexts/TokensContext';
 import WalletProvider from './contexts/wallet/WalletProvider';
+import { ConfigProvider } from './contexts/ConfigContext';
 import type { WormholeConnectWalletProvider } from './utils/wallet/types';
 import { internalWalletProvider } from './utils/wallet/InternalWalletProvider';
 
@@ -56,13 +57,15 @@ export default function WormholeConnect({
       <ThemeProvider theme={muiTheme}>
         <ScopedCssBaseline enableColorScheme>
           <ErrorBoundary>
-            <WalletProvider provider={walletProvider}>
-              <TokensProvider>
-                <RouteProvider>
-                  <AppRouter config={config} />
-                </RouteProvider>
-              </TokensProvider>
-            </WalletProvider>
+            <ConfigProvider config={config}>
+              <WalletProvider provider={walletProvider}>
+                <TokensProvider>
+                  <RouteProvider>
+                    <AppRouter />
+                  </RouteProvider>
+                </TokensProvider>
+              </WalletProvider>
+            </ConfigProvider>
           </ErrorBoundary>
         </ScopedCssBaseline>
       </ThemeProvider>

src/WormholeConnect.tsx

@@ -171,6 +171,28 @@ export function buildConfig(
 
 // Running buildConfig with no argument generates the default configuration
 const config = buildConfig();
+
+/**
+ * @deprecated Direct import of config singleton is deprecated.
+ * Use `useConfig()` hook from 'contexts/ConfigContext' instead.
+ *
+ * This singleton will be removed in a future version to support
+ * multiple WormholeConnect instances on the same page.
+ *
+ * Migration:
+ * ```tsx
+ * // Before (deprecated)
+ * import config from 'config';
+ * const network = config.network;
+ *
+ * // After (recommended)
+ * import { useConfig } from 'contexts/ConfigContext';
+ * function MyComponent() {
+ *   const config = useConfig();
+ *   const network = config.network;
+ * }
+ * ```
+ */
 export default config;
 
 export async function getWormholeContextV2(): Promise<WormholeV2<Network>> {
@@ -214,8 +236,14 @@ export async function newWormholeContextV2(): Promise<WormholeV2<Network>> {
   );
 }
 
-// setConfig can be called afterwards to override the default config with integrator-provided config
-
+/**
+ * @deprecated setConfig() is deprecated and will be removed in a future version.
+ * Configuration is now handled by ConfigProvider. Pass config directly to
+ * <WormholeConnect config={...} /> instead.
+ *
+ * This function mutates the global singleton which prevents multiple
+ * WormholeConnect instances from having independent configurations.
+ */
 export function setConfig(customConfig: WormholeConnectConfig = {}) {
   const newConfig: InternalConfig<Network> = buildConfig(customConfig);
 

src/config/index.ts

@@ -0,0 +1,98 @@
+import * as React from 'react';
+import type { Network } from '@wormhole-foundation/sdk';
+import type { WormholeConnectConfig, InternalConfig } from '../config/types';
+import { buildConfig, setConfig } from '../config';
+import config from '../config';
+
+export type ConfigContextType = InternalConfig<Network>;
+
+const ConfigContext = React.createContext<ConfigContextType | null>(null);
+
+export interface ConfigProviderProps {
+  config?: WormholeConnectConfig;
+  children: React.ReactNode;
+}
+
+/**
+ * ConfigProvider builds and provides instance-scoped configuration.
+ *
+ * Phase 1: During transition, this provider also calls setConfig() to maintain
+ * backwards compatibility with the global singleton. This ensures existing code
+ * that imports `config` directly continues to work.
+ *
+ * Future phases will remove the setConfig() call and the global singleton entirely.
+ */
+export const ConfigProvider: React.FC<ConfigProviderProps> = ({
+  config: userConfig,
+  children,
+}) => {
+  // Build instance-specific config from user config
+  // Memoize to prevent rebuilding on every render
+  const internalConfig = React.useMemo(() => {
+    // Build the config for this instance
+    const builtConfig = buildConfig(userConfig);
+
+    // Phase 1: Also update global singleton for backwards compatibility
+    // This ensures files that directly import config still work
+    // TODO: Remove in Phase 5 when singleton is eliminated
+    if (userConfig) {
+      setConfig(userConfig);
+    }
+
+    return builtConfig;
+  }, [userConfig]);
+
+  // Trigger events on config changes (mirrors AppRouter behavior)
+  const hasInitialized = React.useRef(false);
+  React.useEffect(() => {
+    if (!hasInitialized.current) {
+      hasInitialized.current = true;
+      config.triggerEvent({
+        type: 'load',
+        config: userConfig,
+      });
+    } else {
+      config.triggerEvent({
+        type: 'config',
+        config: userConfig,
+      });
+    }
+  }, [userConfig]);
+
+  return (
+    <ConfigContext.Provider value={internalConfig}>
+      {children}
+    </ConfigContext.Provider>
+  );
+};
+
+/**
+ * useConfig returns the instance-scoped configuration.
+ *
+ * This hook must be used within a ConfigProvider. It returns the InternalConfig
+ * object built from the user-provided WormholeConnectConfig.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const config = useConfig();
+ *   return <div>Network: {config.network}</div>;
+ * }
+ * ```
+ *
+ * @throws Error if used outside of ConfigProvider
+ */
+export function useConfig(): ConfigContextType {
+  const contextValue = React.useContext(ConfigContext);
+
+  if (contextValue === null) {
+    throw new Error(
+      'useConfig must be used within a ConfigProvider. ' +
+        'Ensure your component is wrapped in <WormholeConnect> or <ConfigProvider>.',
+    );
+  }
+
+  return contextValue;
+}
+
+export { ConfigContext };

src/contexts/ConfigContext.tsx

@@ -3,6 +3,8 @@
 interface ImportMetaEnv {
   // env
   REACT_APP_CONNECT_ENV: string;
+  REACT_APP_CONNECT_VERSION?: string;
+  REACT_APP_CONNECT_GIT_HASH?: string;
 
   // wallet connect
   REACT_APP_WALLET_CONNECT_PROJECT_ID: string;
@@ -66,6 +68,14 @@ interface ImportMetaEnv {
   REACT_APP_PLUME_TESTNET_RPC: string;
   REACT_APP_XRPLEVM_TESTNET_RPC: string;
   REACT_APP_MONAD_TESTNET_RPC: string;
+  REACT_APP_LINEA_TESTNET_RPC?: string;
+  REACT_APP_SONIC_TESTNET_RPC?: string;
+  REACT_APP_INK_TESTNET_RPC?: string;
+
+  // test private keys (dev only)
+  REACT_APP_TEST_EVM_PK?: string;
+  REACT_APP_SOL_PRIVATE_KEY?: string;
+  REACT_APP_SUI_PRIVATE_KEY?: string;
 
   // devnet
   REACT_APP_ETHEREUM_DEVNET_RPC: string;

src/env.d.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from 'react';
+import * as React from 'react';
+import type { Token } from 'config/tokens';
+
+// Test-only context that mirrors ConfigContext without importing it
+// This avoids triggering SDK import chains during tests
+const TestConfigContext = React.createContext<unknown>(null);
+
+// Export for tests that need direct access
+export { TestConfigContext };
+
+/**
+ * Test wrapper that provides ConfigContext directly with a pre-built config.
+ *
+ * This bypasses ConfigProvider's buildConfig() call which has deep SDK dependencies.
+ * Use this for unit tests that need useConfig() to return a specific mock config.
+ *
+ * IMPORTANT: Tests using this wrapper MUST mock 'contexts/ConfigContext' to use
+ * TestConfigContext, otherwise useConfig() won't receive the mock config.
+ *
+ * For integration tests, use ConfigProvider directly with a real config.
+ */
+export interface TestWrapperOptions {
+  /**
+   * Pre-built config object to provide via context.
+   * This should be a partial InternalConfig with the fields your test needs.
+   */
+  config?: Record<string, unknown>;
+}
+
+export const createTestWrapper = (options: TestWrapperOptions = {}) => {
+  const { config } = options;
+
+  const TestWrapper = ({ children }: { children: ReactNode }) => (
+    <TestConfigContext.Provider value={config}>
+      {children}
+    </TestConfigContext.Provider>
+  );
+
+  return TestWrapper;
+};
+
+/**
+ * Helper to create mock tokens for testing
+ */
+export const createMockToken = (overrides: Partial<Token> = {}): Token => {
+  const chain = overrides.chain || 'Ethereum';
+  const addressString = overrides.addressString || '0x1234567890abcdef';
+  const address = overrides.address || addressString;
+
+  return {
+    chain,
+    addressString,
+    address,
+    symbol: 'TEST',
+    name: 'Test Token',
+    decimals: 18,
+    isNativeGasToken: false,
+    isTokenBridgeWrappedToken: false,
+    isBuiltin: false,
+    tokenId: {
+      chain,
+      address,
+    },
+    ...overrides,
+  } as Token;
+};