Skip to main content

Migrating React Applications from v9 to v10

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

For general migration points (chain configuration, MFA, method renames, etc.), 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 (e.g., 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.

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.

On this page