Migrating React applications from v9 to v10

This guide focuses specifically on migrating React applications from Embedded Wallets/Web3Auth v9 to v10. This is a supplementary guide to the main v9 to v10 migration guide.

For general migration points (such as chain configuration, MFA, method renames), please refer to the main migration guide.

Migrating a React application

This section focuses on changes specific to migrating a Web3Auth v9 React application to v10 using @web3auth/modal/react.

React hooks path and WalletServicesPlugin updates

Previously, React hooks were at @web3auth/modal-react-hooks. Now, they are consolidated and imported from @web3auth/modal/react. Even WalletServicesPlugin is now integrated into the hooks. Previously, it was a separate package named @web3auth/wallet-services-plugin-react-hooks.

The Web3AuthProvider component remains essential for initializing the Web3Auth SDK and providing its context. Key changes include:

• Import path: Web3AuthProvider is imported from @web3auth/modal/react.
• Configuration Prop: Web3AuthProvider in v10 typically takes a single config prop. This config object (for example, web3AuthContextConfig) will contain your web3AuthOptions and any client-side SDK configurations.
• Dashboard configuration: Many configurations (like chain details for standard EVM chains, and verifier/connection settings) are now primarily managed through the Web3Auth Developer Dashboard (now the Embedded Wallets dashboard).

v10 Web3AuthProvider and hook usage

Web3AuthProvider is configured with a config object, and all hooks are streamlined under @web3auth/modal/react.

main.tsx / index.tsx

import ReactDOM from "react-dom/client";
import { Web3AuthProvider } from "@web3auth/modal/react"; // v10 import
import web3AuthContextConfig from "./web3authContext"; // see context file below
import App from "./App";

// Example with Wagmi, though not strictly necessary for Web3AuthProvider
import { WagmiProvider } from "@web3auth/modal/react/wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
const queryClient = new QueryClient();


ReactDOM.createRoot(document.getElementById("root")!).render(
  <Web3AuthProvider config={web3AuthContextConfig}>
    <QueryClientProvider client={queryClient}>
      <WagmiProvider>
        <App />
      </WagmiProvider>
    </QueryClientProvider>
  </Web3AuthProvider>
);

web3authContext.ts

import { WEB3AUTH_NETWORK, Web3AuthOptions } from '@web3auth/modal' // v10 modal options
import { type Web3AuthContextConfig } from '@web3auth/modal/react' // v10 context config type

const clientId = 'YOUR_V10_CLIENT_ID' // Get from https://dashboard.web3auth.io

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId,
    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  },
}

export default web3AuthContextConfig

All hooks are now streamlined under @web3auth/modal/react:

App.tsx

import {
  useWeb3Auth,
  useWeb3AuthConnect,
  useWeb3AuthDisconnect,
  useIdentityToken,
  useWeb3AuthUser,
  useSwitchChain,
  useEnableMFA,
  useManageMFA,
  useWalletConnectScanner, // Wallet Services
  useWalletUI, // Wallet Services
  useCheckout, // Wallet Services
  useSwap, // Wallet Services
  useWalletServicesPlugin, // Wallet Services
} from '@web3auth/modal/react'

React hook structure

The new hook structure is more granular:

• Core Web3Auth:
  • useWeb3Auth: Core hook for initialization status and overall SDK state.
• Authentication:
  • useWeb3AuthConnect: Handles connection.
  • useWeb3AuthDisconnect: Manages Disconnection.
• Identity:
  • useIdentityToken: Retrieves identity tokens.
  • useWeb3AuthUser: Accesses authenticated user's information.
• Blockchain:
  • useSwitchChain: Allows switching networks.
• MFA:
  • useEnableMFA: Enables MFA.
  • useManageMFA: Manages MFA settings.
• Wallet Services plugin (now integrated):
  • useWalletServicesPlugin: Hook to access the Wallet Services plugin context.
    • isPluginConnected: boolean
    • showWalletConnectScanner(params?): Promise<void>
    • showCheckout(params?): Promise<void>
    • showWalletUI(params?): Promise<void>
    • showSwap(params?): Promise<void>

Refer to the React Modal SDK hooks documentation for the detailed SDK reference.

Package removal

When migrating React applications, ensure you remove these deprecated packages:

• @web3auth/modal-react-hooks
• @web3auth/wallet-services-plugin-react-hooks

Next steps

Return to the main v9 to v10 migration guide to continue with other migration aspects like MFA configurations, method renames, and chain configuration changes.