Web3Auth v10 React & Vue Migration Guide

This guide focuses specifically on migrating React and Vue 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.

Migrating a Vue Application

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

Vue Composables Path and WalletServicesPlugin Updates

Previously, Vue composables were at @web3auth/modal-vue-composables. Now, they are consolidated and imported from @web3auth/modal/vue. WalletServicesPlugin functionality is also integrated into these composables, whereas previously with v9 it was imported via @web3auth/wallet-services-plugin-vue-composables.

v10 Vue Composables Usage

All composables are now streamlined under @web3auth/modal/vue:

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/vue";

Vue Composable Structure

The new composable structure is more granular:

• Core Web3Auth:
  • useWeb3Auth: Core composable for Web3Auth initialization and state management.
• Authentication:
  • useWeb3AuthConnect: Handles Web3Auth connection processes.
  • useWeb3AuthDisconnect: Manages disconnection from Web3Auth.
• Identity:
  • useIdentityToken: Retrieves and manages identity tokens.
  • useWeb3AuthUser: Provides access to the authenticated user's information.
• Blockchain:
  • useSwitchChain: Allows switching between different blockchain networks.
• MFA:
  • useEnableMFA: Enables Multi-Factor Authentication (MFA) for enhanced security.
  • useManageMFA: Provides functionality to manage MFA settings.
• Wallet Services Plugin (now integrated):
  • useWalletServicesPlugin: Composable to access the Wallet Services Plugin context and its functions.
  • useWalletConnectScanner: Integrates WalletConnect scanner functionality.
  • useWalletUI: Manages wallet UI components and user interactions.
  • useCheckout: Facilitates cryptocurrency checkout processes.
  • useSwap: Enables token swapping capabilities.

Please refer to the Vue Modal SDK documentation for the SDK reference.

Package Removal

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

• @web3auth/modal-react-hooks (for React users)
• @web3auth/modal-vue-composables (for Vue users)
• @web3auth/wallet-services-plugin-react-hooks (for React users)
• @web3auth/wallet-services-plugin-vue-composables (for Vue users)

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.