Skip to main content

Web3Auth No-Modal v9 to v10 Migration Guide

Recommended: Switch to Modal SDK

While the @web3auth/no-modal package continues to receive updates, it now primarily serves as an internal SDK to power the modal SDK. We strongly recommend migrating to the @web3auth/modal package for the best developer experience.

The Modal SDK offers everything you need: pre-built UI components for quick integration AND full custom UI control via connectTo for advanced use cases. Plus, you'll get priority documentation, examples, and community support.

This guide will help you upgrade your Web3Auth No-Modal SDK integration from v9 to the unified Web3Auth PnP Web SDK v10, which consolidates both modal and no-modal functionality into a single package.

Why Migrate to v10?​

Web3Auth v10 unifies the modal and no-modal SDKs into a single powerful package. Whether you want a pre-built modal UI or a custom implementation, you now use the same @web3auth/modal package with connectTo for no-modal-like functionality.

Key improvements from v9 no-modal to v10:

  • Unified SDK Package: Single @web3auth/modal package replaces @web3auth/no-modal
  • Dashboard-Centric Configuration: Chain configurations managed via Web3Auth Developer Dashboard
  • Simplified Integration: No more manual adapter registration and configuration
  • Enhanced Developer Experience: Cleaner API with better TypeScript support
  • Custom UI Support: Use connectTo for seamless custom UI implementations

Installation​

Update to the unified v10 SDK package:

npm uninstall @web3auth/no-modal @web3auth/auth-adapter @web3auth/wallet-services-plugin
npm install @web3auth/modal

For custom blockchain configurations:

npm install @web3auth/ethereum-provider

Breaking Changes from v9 to v10​

1. Package Migration: No-Modal → Modal​

v9 used separate no-modal package:

import { Web3AuthNoModal } from "@web3auth/no-modal";
import { AuthAdapter } from "@web3auth/auth-adapter";
import { WalletServicesPlugin } from "@web3auth/wallet-services-plugin";

v10 uses unified modal package:

import { Web3Auth } from "@web3auth/modal";
// Most functionality is now built-in - no separate adapters needed for basic use cases

2. Class Name Change: Web3AuthNoModal → Web3Auth​

v9 initialization:

import { Web3AuthNoModal } from "@web3auth/no-modal";

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

v10 initialization:

import { Web3Auth } from "@web3auth/modal";

const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain configuration managed via Web3Auth Developer Dashboard
});

3. No-Modal Functionality: Direct Connection → connectTo​

v9 approach for custom UI:

const authAdapter = new AuthAdapter({
  adapterSettings: {
    loginConfig: {
      google: {
        verifier: "YOUR_GOOGLE_VERIFIER_NAME",
        typeOfLogin: "google",
        clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
      },
    },
  },
});

web3auth.configureAdapter(authAdapter);
await web3auth.init();

// Custom UI - connect directly
await web3auth.connectTo("auth", {
  loginProvider: "google",
});

v10 approach for custom UI:

await web3auth.init();

// Custom UI - use connectTo
await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
});

// Or with custom verifiers/connections
await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
  authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID",
});

4. Chain Configuration Centralization​

v9 required manual chain and provider configuration:

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

const chainConfig = {
  chainNamespace: "eip155",
  chainId: "0x1",
  rpcTarget: "https://rpc.ethereum.org",
  displayName: "Ethereum Mainnet",
  blockExplorer: "https://etherscan.io/",
  ticker: "ETH",
  tickerName: "Ethereum",
};

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

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

v10 handles standard chains automatically via dashboard:

const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain configuration managed via Web3Auth Developer Dashboard
});

Configure your chains on the Web3Auth Developer Dashboard instead of in code.

Next Steps​

  1. Update your package dependencies
  2. Migrate your initialization code to use Web3Auth from @web3auth/modal
  3. Replace direct adapter methods with connectTo calls
  4. Configure your chains and branding on the Web3Auth Developer Dashboard
  5. Test your custom UI implementation with the new connectTo API

For any specific migration challenges, consult the Web3Auth documentation.