Web3Auth No-Modal v8 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 v8 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 v8 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

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

Yarn

yarn remove @web3auth/no-modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
yarn add @web3auth/modal

pnpm

pnpm remove @web3auth/no-modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
pnpm add @web3auth/modal

Bun

bun remove @web3auth/no-modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
bun add @web3auth/modal

For custom blockchain configurations:

npm

npm install @web3auth/ethereum-provider

Yarn

yarn add @web3auth/ethereum-provider

pnpm

pnpm add @web3auth/ethereum-provider

Bun

bun add @web3auth/ethereum-provider

Breaking Changes from v8 to v10

1. Package Migration: No-Modal → Modal

v8 used separate no-modal package:

import { Web3AuthNoModal } from "@web3auth/no-modal";
import { OpenloginAdapter } from "@web3auth/openlogin-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

v8 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

v8 approach for custom UI:

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

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

// Custom UI - connect directly
await web3auth.connectTo("openlogin", {
  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

v8 required manual chain and provider configuration:

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

const chainConfig = getEvmChainConfig(1, "YOUR_CLIENT_ID");

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.

Additional Migration Guides

For specific functionality migrations, refer to these supplementary guides:

External Wallet Adapters: If you used external wallet adapters in v8, see the 🔌 External Wallet Adapters Migration Guide for migrating to automatic detection.

Wallet Services: If you used the @web3auth/wallet-services-plugin in v8, see the 🛠️ Wallet Services Migration Guide for migrating to the built-in integration.

Whitelabeling and UI Customization: If you had whitelabeling configurations in v8, see the 📋 Whitelabeling Migration Guide for detailed steps.

Custom Authentication: If you used custom verifiers in v8, see the 🔐 Custom Authentication Migration Guide for migrating to the new Connections system.

Complete Migration Example

Here's a complete before/after example showing the migration from v8 no-modal to v10:

v8 No-Modal Implementation

import { Web3AuthNoModal } from "@web3auth/no-modal";
import { OpenloginAdapter } from "@web3auth/openlogin-adapter";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { getDefaultExternalAdapters } from "@web3auth/default-evm-adapter";

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

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

// SDK initialization
const web3auth = new Web3AuthNoModal({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: "sapphire_mainnet",
  privateKeyProvider,
  uiConfig: {
    appName: "My App",
    logoLight: "https://example.com/logo-light.png",
    logoDark: "https://example.com/logo-dark.png",
  },
});

// Openlogin adapter
const openloginAdapter = new OpenloginAdapter({
  adapterSettings: {
    loginConfig: {
      google: {
        verifier: "YOUR_GOOGLE_VERIFIER_NAME",
        typeOfLogin: "google",
        clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
      },
    },
  },
});

web3auth.configureAdapter(openloginAdapter);

// External adapters
const adapters = await getDefaultExternalAdapters({
  options: { clientId: "YOUR_CLIENT_ID", chainConfig },
});
adapters.forEach((adapter) => {
  web3auth.configureAdapter(adapter);
});

await web3auth.init();

// Connect with custom UI
await web3auth.connectTo("openlogin", {
  loginProvider: "google",
});

v10 Unified Implementation

import { Web3Auth, WALLET_CONNECTORS, AUTH_CONNECTION } from "@web3auth/modal";

// SDK initialization - much simpler!
const web3auth = new Web3Auth({
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: "sapphire_mainnet",
  // Chain config and branding managed via dashboard
});

await web3auth.init();

// Connect with custom UI using connectTo
await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
  authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID", // From dashboard
});

// External wallets automatically detected - no manual setup needed
// await web3auth.connectTo(WALLET_CONNECTORS.WALLET, {
//   provider: "metamask"
// });

Key Differences Summary

Feature	v8 No-Modal	v10 Unified
Package	@web3auth/no-modal	@web3auth/modal
Class	Web3AuthNoModal	Web3Auth
Custom UI	Direct adapter methods	connectTo method
Chain Config	Manual chainConfig + privateKeyProvider	Dashboard configuration
External Wallets	Manual adapter setup	Automatic detection
Verifiers	Manual loginConfig	Dashboard Connections
Branding	uiConfig in SDK	Dashboard configuration

Benefits of v10 Migration

1. Unified Architecture: Single package handles both modal and custom UI use cases
2. Reduced Complexity: No manual adapter configuration or chain setup
3. Dashboard Control: Centralized configuration management
4. Better Developer Experience: Cleaner API with improved TypeScript support
5. Future-Proof: Aligned with Web3Auth's long-term architectural direction

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, refer to the supplementary guides linked above or consult the Web3Auth documentation.