Skip to main content

Web3Auth web SDK v8 to v10 migration guide

This guide will help you upgrade your Web3Auth SDK integration from v8 directly to the unified Web3Auth Web SDK v10, focusing on core package and initialization changes.

Why migrate to v10?​

Web3Auth v10 consolidates functionality into a single powerful SDK that centralizes configuration in the dashboard and eliminates frontend adapter complexity.

Key improvements from v8 to v10:

  • Unified SDK Package: Single @web3auth/modal package replaces multiple adapter packages
  • Dashboard-Centric Configuration: Chain configurations managed via Web3Auth Developer Dashboard (now the Embedded Wallets dashboard)
  • Simplified Integration: No more manual OpenLoginAdapter registration
  • Enhanced Developer Experience: Cleaner API with better TypeScript support

Installation​

Update to the unified v10 SDK package:

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

For custom blockchain configurations:

npm install @web3auth/ethereum-provider

Breaking changes from v8 to v10​

1. Unified SDK package structure​

v8 used separate packages:

import { Web3Auth } from '@web3auth/modal'
import { OpenloginAdapter } from '@web3auth/openlogin-adapter'
import { WalletServicesPlugin } from '@web3auth/wallet-services-plugin'

v10 uses a single package:

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

2. Openloginadapter → authadapter → built-in (v8→v9→v10)​

In v8, authentication used OpenloginAdapter. V9 renamed it to AuthAdapter. V10 eliminates the need for separate adapters in most cases.

import { OpenloginAdapter } from '@web3auth/openlogin-adapter'

const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: 'optional',
  },
  adapterSettings: {
    whiteLabel: {
      name: 'Your App',
      logoLight: 'https://example.com/logo-light.png',
      logoDark: 'https://example.com/logo-dark.png',
    },
  },
})

web3auth.configureAdapter(openloginAdapter)

import { WEB3AUTH_NETWORK, MFA_LEVELS } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // MFA and branding now configured here or via dashboard
  mfaLevel: MFA_LEVELS.OPTIONAL,
})

3. 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 Web3Auth({
  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 Embedded Wallets dashboard instead of in code.

4. Method name changes​

// Parameter rename
const web3auth = new Web3Auth({
  useCoreKitKey: true,
  useSFAKey: true,
})

// Method rename
const userAuthInfo = await web3auth.authenticateUser()
const userAuthInfo = await web3auth.getIdentityToken()
const idToken = userAuthInfo.idToken

External Wallet Adapters: If you used external wallet adapters (for example, MetaMask, Phantom, Solflare) in v8, see the 🔌 External Wallet Adapters Migration Guide for migrating to the automatic detection system.

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 to v10:

import { Web3Auth } from '@web3auth/modal'
import { OpenloginAdapter } from '@web3auth/openlogin-adapter'
import { EthereumPrivateKeyProvider } from '@web3auth/ethereum-provider'
import { getEvmChainConfig } from '@web3auth/base'

const clientId = 'YOUR_CLIENT_ID'
const chainConfig = getEvmChainConfig(1, clientId)

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

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

const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: 'optional',
  },
  adapterSettings: {
    whiteLabel: {
      name: 'Your App',
      logoLight: 'https://example.com/logo-light.png',
    },
  },
})

web3auth.configureAdapter(openloginAdapter)
await web3auth.initModal()

Dashboard configuration required​

With v10, configurations that were previously done in code are now managed through the Web3Auth Developer Dashboard:

  1. Chain Configurations: Add and configure your blockchain networks
  2. Branding and UI: Set app name, logos, colors, and themes
  3. Login Methods: Enable/disable social login providers

Configure these settings from the Web3Auth Developer Dashboard.

Next steps​

On this page