Skip to main content

Web3Auth PnP No Modal SDK v10 Migration Guide

This guide will help you upgrade your Web3Auth PnP No Modal SDK integration from v9 to v10.

Version 10 significantly simplifies your Web3Auth integration by centralizing configuration in the Web3Auth Developer Dashboard and removing the complexity of adapters, verifiers, and manual blockchain configuration from your frontend code. React integrations now exclusively use a hooks-based approach.

Before You Start

To ensure a smooth migration, please consider the following steps:

  • Backup Your Project: It's crucial to have a backup or a version control checkpoint of your project before starting the migration process.
  • Use Latest v9.x Version: Ensure your application is on the latest Web3Auth v9.x version. This can provide helpful deprecation warnings from the SDK itself.
  • Web3Auth Developer Dashboard Access: A key aspect of v10 is that many configurations (like verifiers, chain settings, and Smart Accounts) are now managed via the Web3Auth Developer Dashboard. Make sure you have access to your project settings on the dashboard.
  • Understand the Scope: Briefly review the "Why these changes?" and "Migration Overview" sections to understand the scope and nature of the upgrade.
  • Allocate Sufficient Time: Go through this guide once entirely to estimate the time and effort required for your specific integration.
Key Change in v10: Dashboard-Centric Configuration

Remember, a fundamental shift in v10 is moving many configurations that were previously in your client-side code (like verifier details, chain configurations, and Smart Account settings) to the Web3Auth Developer Dashboard. Throughout this guide, when client-side code is removed, it's often because that configuration now resides on the dashboard.

Why these changes?​

Web3Auth v9 was designed for flexibility, but it often led to verbose setup and configuration overhead. Common issues included:

  • Manual adapter registration: Developers had to import and configure adapters like AuthAdapter, often duplicating login method declarations.
  • Frontend-managed verifiers: Account linking required setting verifier and verifierSubIdentifier manually for each login provider, creating potential for drift between frontend and backend logic.
  • Explicit blockchain configuration: Every app needed to manually construct a chainConfig object and pass a privateKeyProvider, even for commonly used chains.
  • Smart Account complexity: Integrating Smart Accounts required understanding and configuring additional providers like bundlers and paymasters using a separate SDK.

Web3Auth v10 simplifies all of this by introducing:

  • Dashboard-centric configuration: Login methods, verifiers, chain details, and Smart Account settings are now managed through the Web3Auth Developer Dashboard—eliminating duplication and reducing error-prone frontend logic.
  • Automatic blockchain config resolution: You no longer need to pass chainConfig or privateKeyProvider. The SDK automatically applies correct settings based on your dashboard config.
  • Declarative login setup via connect: Replaces adapter-based setup with a direct call to connect (or connectTo for non-React) with connection details.
  • React-first hooks API: The SDK now exposes hooks like useWeb3AuthConnect() for React apps to align with modern React patterns and simplify lifecycle and state management. For non-React apps, direct class usage is maintained.
  • Simplified Smart Accounts: All Smart Account logic is abstracted and optionally overridden via accountAbstraction config, with no need for a separate provider SDK.

The result is a cleaner, more declarative, and more maintainable integration experience—especially for teams maintaining apps across multiple auth flows and chains.

Migration Overview​

You'll migrate your app following these steps, ordered from simplest to most complex for minimum cognitive load:

  1. Install Web3Auth No Modal v10.
  2. Replace verifier and verifierSubIdentifier.
  3. Remove adapters.
  4. Remove privateKeyProvider and chainConfig.
  5. Migrate React usage to hooks (required for React users).
  6. Use Wagmi for blockchain RPC interactions (React + EVM chains).
  7. Update Smart Accounts setup (optional).
  8. Update web3authContext.tsx structure (React only).
  9. Consolidate imports to @web3auth/no-modal.
  10. Review deprecated APIs.
  11. Confirm changes with a migration summary.

Installation​

Install the latest v10 SDK package:

npm install @web3auth/no-modal@latest

Remove deprecated packages if present:

  • @web3auth/base
  • @web3auth/auth-adapter
  • @web3auth/account-abstraction-provider
Important

Ensure these packages are fully removed to avoid unexpected behavior during migration.

Step-by-step migration​

Below are detailed instructions for each migration step. Complete them sequentially for clarity and minimal complexity.

1. Replace verifier and verifierSubIdentifier​

Verifiers and sub-verifiers are now managed via your dashboard. Use authConnectionId and groupedAuthConnectionId (when linking accounts) passed directly to the connect or connectTo methods.

// Example of how loginConfig was structured for adapters
loginConfig: {
  google: {
    verifier: "aggregate-verifier", // Name of your aggregate verifier
    verifierSubIdentifier: "w3a-google", // Sub-verifier identifier
    typeOfLogin: "google",
    clientId: "<GOOGLE_CLIENT_ID>", // Google Client ID
  },
  // ... other providers
}

2. Remove adapters​

Adapters like AuthAdapter are removed. Login methods are now configured via the Dashboard and connection details are passed directly to connect or connectTo.

import { AuthAdapter } from "@web3auth/auth-adapter";
// const adapterSettings = { /* ... */ };

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

3. Remove privateKeyProvider and chainConfig​

Explicit blockchain configuration via privateKeyProvider and chainConfig is now fully handled through the Web3Auth Dashboard.

import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { getEvmChainConfig } from "@web3auth/config"; // Example

const clientId = "YOUR_CLIENT_ID";
const chainConfig = getEvmChainConfig(0xaa36a7, clientId); // Example: Sepolia Testnet
const privateKeyProvider = new EthereumPrivateKeyProvider({
  config: { chainConfig },
});

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

4. Migrate React usage to hooks (React only)​

React apps must now use hooks from @web3auth/no-modal/react. Class-based methods are removed for React.

// Class-based example in a React context
const web3auth = new Web3AuthNoModal({
  /* ... options ... */
});
await web3auth.init();
await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  /* ... */
});

For non-React environments (Angular, Svelte, Vue, VanillaJS), you continue to use the Web3AuthNoModal class:

v10 - Angular/VanillaJS Example
import {
  Web3AuthNoModal,
  WALLET_CONNECTORS,
  AUTH_CONNECTION,
  WEB3AUTH_NETWORK,
} from "@web3auth/no-modal";

const web3auth = new Web3AuthNoModal({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
});

await web3auth.init();
await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
  authConnectionId: "your-google-connection-id", // From Dashboard
});
// const provider = web3auth.provider;

✅ Class-based SDK usage remains valid and is the standard for non-React environments.

5. Use Wagmi for blockchain RPC (React + EVM only)​

Replace manual RPC handling with Wagmi hooks for simplicity in React apps on EVM chains.

// Assuming 'provider' is obtained from Web3Auth
// import { ethers } from "ethers";
// const ethersProvider = new ethers.providers.Web3Provider(provider);
// const signer = ethersProvider.getSigner();
// await signer.getAddress();
// await signer.signMessage("Hello World");

For non-React apps, continue using libraries like ethers.js or viem directly with the provider from web3auth.provider.

6. Smart Accounts setup (optional)​

Previously, configuring the adapter required installing the @web3auth/account-abstraction-provider package and using the AccountAbstractionProvider to set up the bundler, paymaster, and Smart Account Provider.

import {
  AccountAbstractionProvider,
  SafeSmartAccount,
} from "@web3auth/account-abstraction-provider";
import { Web3AuthNoModal, WEB3AUTH_NETWORK } from "@web3auth/no-modal"; // Assuming privateKeyProvider is also imported or available

// Assume privateKeyProvider is initialized appropriately, e.g.:
// import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
// const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { /* ... */ } });

// Assume pimlicoAPIKey is defined
// const pimlicoAPIKey = "YOUR_PIMLICO_API_KEY";

// 1. Initialize Web3AuthNoModal first
const web3auth = new Web3AuthNoModal({
  clientId: "YOUR_WEB3AUTH_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  privateKeyProvider, // This should be an initialized PrivateKeyProvider
});
await web3auth.init();
// Example: Connect to a login provider
// await web3auth.connectTo(WALLET_CONNECTORS.OPENLOGIN, { /* loginProvider specific details */ });

// 2. Then initialize AccountAbstractionProvider with the provider from Web3AuthNoModal
const chainConfig = {
  // Chain config (example placeholder, replace with actual v9 config)
  chainId: "0x1", // Example: Ethereum Mainnet
  rpcTarget: "https://rpc.ankr.com/eth",
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io/",
  ticker: "ETH",
  tickerName: "Ethereum",
};

if (web3auth.provider) {
  const accountAbstractionProvider = new AccountAbstractionProvider({
    config: {
      chainConfig,
      smartAccountInit: new SafeSmartAccount(),
      bundlerConfig: {
        // Get the pimlico API Key from dashboard.pimlico.io
        url: `https://api.pimlico.io/v2/11155111/rpc?apikey=${"YOUR_PIMLICO_API_KEY_VARIABLE"}`,
      },
    },
  });
  await accountAbstractionProvider.init(web3auth.provider);
  // const smartAccountProvider = accountAbstractionProvider.provider;
} else {
  console.error("Web3Auth provider not available to initialize Smart Account provider.");
}

7. Update web3authContext.tsx structure (React only)​

In v10, only minimal SDK options are required for the Web3AuthProvider — no adapters or providers.

// Simplified example of old Web3AuthProvider setup
const web3AuthContextConfig = {
  web3AuthOptions: {
    clientId,
    // privateKeyProvider might have been initialized and passed here
    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  },
  // adapters: [...] array of adapter instances,
  // plugins: [...]
};

// <Web3AuthProvider config={web3AuthContextConfig}>
//  <App />
// </Web3AuthProvider>

8. Consolidate imports to @web3auth/no-modal​

Most imports are now available directly from @web3auth/no-modal or @web3auth/no-modal/react.

import { WEB3AUTH_NETWORK } from "@web3auth/base";
import { Web3AuthNoModal } from "@web3auth/no-modal";
import { AuthAdapter } from "@web3auth/auth-adapter";
// Other imports from @web3auth/ethereum-provider, etc.

Deprecated APIs​

Review and remove any deprecated APIs:

  • @web3auth/base: Functionality merged into @web3auth/no-modal. See Step 8: "Consolidate imports to @web3auth/no-modal".
  • @web3auth/auth-adapter (and other specific adapter packages like @web3auth/openlogin-adapter): Adapters are no longer configured in client code. See Step 2: "Remove adapters".
  • @web3auth/account-abstraction-provider: Smart Account configuration is now part of @web3auth/no-modal options and primarily dashboard-driven. See Step 6: "Smart Accounts setup (optional)".
  • verifier, verifierSubIdentifier (in client code): Replaced by authConnectionId and groupedAuthConnectionId passed to connect/connectTo, with configuration on the dashboard. See Step 1: "Replace verifier and verifierSubIdentifier".
  • privateKeyProvider, chainConfig (in client code): Replaced by configuration via the Web3Auth Developer Dashboard. See Step 3: "Remove privateKeyProvider and chainConfig".
  • web3auth.configureAdapter(): This method is removed as adapters are no longer configured in the client. See Step 2: "Remove adapters".
  • React class-based methods for Web3AuthNoModal: React integrations must use hooks. See Step 4: "Migrate React usage to hooks (React only)".

Migration Summary​

Confirm all changes using the detailed table provided in the previous sections.

Featurev9 (No Modal)v10 (No Modal)
Verifier Setupverifier, verifierSubIdentifier in client code⛔ Removed. Use authConnectionId & groupedAuthConnectionId in connect()/connectTo(). Configured in Dashboard.
Account LinkingManual via aggregate verifiers in client code✅ Simplified via groupedAuthConnectionId. Configuration via Dashboard.
Adapter SetupRequired (AuthAdapter, etc. imported and configured)⛔ Removed. Connection details passed to connect()/connectTo().
Chain ConfigurationchainConfig & privateKeyProvider required in client code✅ Handled via Web3Auth Developer Dashboard.
Private Key ProviderExplicitly created and passed⛔ No longer needed in constructor. Managed internally.
React SDK SetupClass-based Web3AuthNoModal or older hooks✅ Hooks only (useWeb3AuthConnect, etc.) from @web3auth/no-modal/react.
Non-React SDK SetupClass-based Web3AuthNoModal✅ Still supported, primary method for these environments.
Blockchain RPC (React)Manual RPC via ethers.js/viem with Web3Auth provider✅ Recommended: Use wagmi hooks for EVM chains.
Smart AccountsSeparate @web3auth/account-abstraction-provider, manual config✅ Dashboard-driven, optional accountAbstraction config in SDK. Deprecated provider package.
Core Package@web3auth/base, @web3auth/no-modal, adapter packages✅ Consolidate to @web3auth/no-modal and @web3auth/no-modal/react.
Context (React)Web3AuthProvider with config prop (adapters, plugins, etc.)✅ Web3AuthProvider with options prop (minimal SDK config).

Verifying Your v10 Integration​

After completing all the migration steps, it's crucial to thoroughly test your application to ensure everything functions as expected. Here's a checklist of areas to focus on:

  • Login Methods: Test every social login, email passwordless, and external wallet connection method you have configured on the Web3Auth Dashboard.
  • Account Consistency: If you use features like groupedAuthConnectionId for account linking, verify that logging in with different methods linked to the same identifier (e.g., same email for Google and a custom JWT) correctly resolves to the same user account and private key.
  • Blockchain Provider: Ensure web3auth.provider (for class-based usage) or the provider from useWeb3Auth() / useWeb3AuthConnect() (for React hooks) is available and correctly initialized for your target chain(s).
  • Core Blockchain Operations:
    • Fetch user account address.
    • Fetch account balance.
    • Sign a message.
    • Send a simple transaction (e.g., a self-transfer of 0 native currency if on a testnet).
  • Smart Accounts (if applicable):
    • Verify that the Smart Account is deployed as expected.
    • Test all key interactions with your Smart Account (e.g., executing transactions, batch transactions if used).
  • Logout Functionality: Ensure logout clears the session and provider correctly.
  • Session Management: If your application relies on session persistence, test that users remain logged in after a page refresh and that sessions are correctly restored.
  • Error Handling: Test common error scenarios (e.g., user cancels login, network issues) to see if they are handled gracefully.

Refer back to the "Migration Summary" table in this guide to double-check that all relevant changes for your integration have been addressed.

Further Reading​