🚀 Migrating to Web3Auth PnP Modal SDK v10

Web3Auth v10 streamlines your authentication experience by centralizing all setup in the Developer Dashboard, removing the complexity of adapters, verifiers, and manual blockchain configuration.

✅ Recommended: Before upgrading, ensure you’re using the latest Web3Auth v9.x to receive helpful deprecation warnings and simplify the migration process.

---

📥 Installation

Start by updating your dependencies to use the latest v10 release:

npm install @web3auth/modal@latest
# or
yarn add @web3auth/modal@latest

⚠️ Note: Ensure removal of deprecated packages like @web3auth/base.

---

🧹 Migration Steps

To migrate effectively, proceed in the following logical order:

1. Update Authentication Configuration
2. Remove Adapter Setup
3. Simplify Chain and Key Provider Setup
4. Update Modal Configuration
5. Switch to React Hooks (if applicable)
6. Update Blockchain RPC Usage
7. Review Deprecated Features

---

1. Update Authentication Configuration

Replace verifier and verifierSubIdentifier with dashboard-based identifiers:

v9 (Before)

loginConfig: {
  google: {
    verifier: "aggregate-verifier",
    verifierSubIdentifier: "w3a-google",
    typeOfLogin: "google",
    clientId: "<GOOGLE_CLIENT_ID>",
  },
}

v10 (After)

modalConfig: {
  connectors: {
    [WALLET_CONNECTORS.AUTH]: {
      loginMethods: {
        google: {
          authConnection: AUTH_CONNECTION.GOOGLE,
          authConnectionId: "w3a-google",
          groupedAuthConnectionId: "group-main",
        },
      },
    },
  },
}

✅ Benefit: Automatic account linking via dashboard, reducing frontend complexity.

---

2. Remove Adapter Setup

Adapters like AuthAdapter are fully removed. Migrate directly to connectors:

v9 (Before)

import { AuthAdapter } from "@web3auth/auth-adapter";

const authAdapter = new AuthAdapter(adapterSettings);
web3auth.configureAdapter(authAdapter);

v10 (After)

modalConfig: {
  connectors: {
    [WALLET_CONNECTORS.AUTH]: {
      loginMethods: {
        google: {
          authConnection: AUTH_CONNECTION.GOOGLE,
          authConnectionId: "w3a-google",
        },
      },
    },
  },
}

✅ Result: Cleaner, zero-import setup.

---

3. Simplify Chain and Key Provider Setup

Manual privateKeyProvider and chainConfig are deprecated. Now fully dashboard-driven:

v9 (Before)

const chainConfig = getEvmChainConfig(chainId, clientId);
const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { chainConfig } });

const web3auth = new Web3Auth({
  clientId,
  privateKeyProvider,
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
});

v10 (After)

const web3auth = new Web3Auth({
  clientId,
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  modalConfig: { ... },
});

---

4. Update Modal Configuration

Move modalConfig setup directly into the SDK constructor:

v9 (Before)

await web3auth.initModal({
  modalConfig: { ... },
});

v10 (After)

const web3auth = new Web3Auth({
  clientId,
  modalConfig: { ... },
});
await web3auth.initModal();

---

5. Switch to React Hooks (if applicable)

React apps must migrate from class-based methods to hooks provided by @web3auth/modal/react:

v9 (Before)

const web3auth = new Web3Auth({ ... });
await web3auth.initModal();
await web3auth.connect();

v10 (After)

const { connect } = useWeb3AuthConnect();

await connect(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
  authConnectionId: "w3a-google",
});

---

6. Update Blockchain RPC Usage (React only)

React-based blockchain RPC calls should now use wagmi hooks:

v9 (Before)

const rpc = new EthereumRpc(provider);
await rpc.getAccounts();
await rpc.signMessage();

v10 (After)

import { useAccount, useSignMessage } from "wagmi";

const { address } = useAccount();
const { signMessage } = useSignMessage();

---

7. Review Deprecated Features

Plan for future removal of deprecated features:

Feature	v10 Status	Action required
@web3auth/base package	Deprecated	Replace with @web3auth/modal
privateKeyProvider	Removed	Dashboard-managed
Class-based React usage	Removed	Switch to hooks
Adapters (AuthAdapter, etc.)	Removed	Use connectors

---

🚦 Framework Compatibility Table

Framework	Class-based usage	React hooks	Wagmi RPC
React	❌ Unsupported	✅ Required	✅ Recommended
Angular	✅ Supported	N/A	N/A
Vue	✅ Supported	N/A	N/A
Vanilla	✅ Supported	N/A	N/A

---

🎯 Summary & Next Steps

• ✅ Review: Verify you've addressed all breaking changes.
• ✅ Testing: Thoroughly test your migrated application.
• ✅ Support: Reach out via our community forums for help.

---

📖 Additional Resources

• Web3Auth Documentation
• PnP Examples