# Migrating to the Web3Auth PnP Web SDK v10 from v7

> Learn what has changed from Web3Auth v7 to the v10 Web SDK with comprehensive migration steps and cleaner architecture.

# Web3Auth PnP web SDK v7 to v10 migration guide

This guide will help you upgrade your Web3Auth PnP SDK integration from v7 directly to the **unified
Web3Auth PnP 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 v7 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](https://developer.metamask.io/))
- **Simplified Integration:** No more manual `OpenLoginAdapter` registration or `privateKeyProvider`
  setup
- **Enhanced Developer Experience:** Cleaner API with better TypeScript support

## Installation

Update to the unified v10 SDK package:

```bash npm2yarn
npm uninstall @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-connect-v2-adapter @web3auth/metamask-adapter @web3auth/phantom-adapter @web3auth/wallet-services-plugin
npm install @web3auth/modal
```

For custom blockchain configurations:

```bash npm2yarn
npm install @web3auth/ethereum-provider
```

## Breaking changes from v7 to v10

### 1. Unified SDK package structure

**v7 used separate packages:**

```typescript
// remove-start

// remove-end
```

**v10 uses a single package:**

```typescript
// add-start

// Most functionality is now built-in - no separate adapters needed for basic use cases
// add-end
```

### 2. Openloginadapter → built-in (v7→v10)

In v7, authentication required `OpenloginAdapter`. V10 eliminates the need for adapter registration:

```typescript
// remove-start

const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: 'optional',
  },
  adapterSettings: {
    whiteLabel: {
      appName: 'W3A Heroes',
      logoLight: 'https://web3auth.io/images/web3auth-logo.svg',
      logoDark: 'https://web3auth.io/images/web3auth-logo---Dark.svg',
    },
  },
})

web3auth.configureAdapter(openloginAdapter)
await web3auth.initModal()
// remove-end

// add-start
// Authentication is built-in - no adapter configuration needed
await web3auth.init()
// add-end
```

### 3. Chain configuration centralization

**v7 required manual chain and provider configuration:**

```typescript
// remove-start

const chainConfig = {
  chainNamespace: 'eip155',
  chainId: '0x1',
  rpcTarget: 'https://rpc.ethereum.org',
  displayName: 'Ethereum Mainnet',
  blockExplorerUrl: 'https://etherscan.io/',
  ticker: 'ETH',
  tickerName: 'Ethereum',
  logo: 'https://images.toruswallet.io/eth.svg',
}

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

const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  privateKeyProvider,
  uiConfig: {
    appName: 'W3A Heroes',
    logoLight: 'https://web3auth.io/images/web3auth-logo.svg',
    logoDark: 'https://web3auth.io/images/web3auth-logo---Dark.svg',
  },
})
// remove-end

// add-start
const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain configuration and branding managed via Web3Auth Developer Dashboard
})
// add-end
```

Configure your chains and branding on the
[Web3Auth Developer Dashboard](https://developer.metamask.io) instead of in code.

### 4. Method name changes

**Key method updates:**

```typescript
// remove-start
// v7 method names
await web3auth.authenticateUser() // Get ID token
await web3auth.addChain(newChain) // Add new chain
await web3auth.switchChain({ chainId: '0x1' }) // Switch chains
// remove-end

// add-start
// v10 method names
await web3auth.getIdentityToken() // Get ID token
await web3auth.addChain(newChain) // Add new chain (unchanged)
await web3auth.switchChain({ chainId: '0x1' }) // Switch chains (unchanged)
// add-end
```

## Additional migration guides

For specific functionality migrations, refer to these supplementary guides:

**External Wallet Adapters:** If you used external wallet adapters in v7, see the 🔌
**[External Wallet Adapters Migration Guide](./external-wallets.mdx)** for migrating
to automatic detection.

**Wallet Services:** If you used the `@web3auth/wallet-services-plugin` in v7, see the 🛠️
**[Wallet Services Migration Guide](./wallet-services.mdx)** for migrating to the
built-in integration.

**Whitelabeling and UI customization:** If you had whitelabeling configurations in v7, see the 📋
**[Whitelabeling Migration Guide](./whitelabeling.mdx)** for detailed steps.

**Custom authentication:** If you used custom verifiers in v7, see the 🔐
**[Custom Authentication Migration Guide](./custom-authentication.mdx)** for
migrating to the new connections system.

## Complete migration example

Here's a complete before/after example showing the migration from v7 to v10:

<Tabs>
<TabItem value="v7" label="v7 Implementation">

```typescript

  WalletConnectV2Adapter,
  getWalletConnectV2Settings,
} from '@web3auth/wallet-connect-v2-adapter'

// Chain configuration
const chainConfig = {
  chainNamespace: 'eip155',
  chainId: '0x1',
  rpcTarget: 'https://rpc.ethereum.org',
  displayName: 'Ethereum Mainnet',
  blockExplorerUrl: 'https://etherscan.io/',
  ticker: 'ETH',
  tickerName: 'Ethereum',
  logo: 'https://images.toruswallet.io/eth.svg',
}

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

// SDK initialization
const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  privateKeyProvider,
  uiConfig: {
    appName: 'W3A Heroes',
    logoLight: 'https://web3auth.io/images/web3auth-logo.svg',
    logoDark: 'https://web3auth.io/images/web3auth-logo---Dark.svg',
  },
})

// OpenLogin adapter
const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: 'optional',
  },
  adapterSettings: {
    whiteLabel: {
      appName: 'W3A Heroes',
      logoLight: 'https://web3auth.io/images/web3auth-logo.svg',
      logoDark: 'https://web3auth.io/images/web3auth-logo---Dark.svg',
    },
  },
})
web3auth.configureAdapter(openloginAdapter)

// External adapters
const metamaskAdapter = new MetamaskAdapter()
web3auth.configureAdapter(metamaskAdapter)

const defaultWcSettings = await getWalletConnectV2Settings('eip155', ['1'], 'projectId')
const walletConnectV2Adapter = new WalletConnectV2Adapter({
  adapterSettings: { qrcodeModal: WalletConnectModal, ...defaultWcSettings.adapterSettings },
  loginSettings: { ...defaultWcSettings.loginSettings },
})
web3auth.configureAdapter(walletConnectV2Adapter)

await web3auth.initModal()

// Usage
await web3auth.connect()
const idToken = await web3auth.authenticateUser()
```

</TabItem>
<TabItem value="v10" label="v10 Implementation">

```typescript

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

await web3auth.init()

// Usage
await web3auth.connect()
const idToken = await web3auth.getIdentityToken()

// External wallets automatically detected - no manual setup needed
```

</TabItem>
</Tabs>

## Key differences summary

| Feature              | v7                                          | v10                     |
| -------------------- | ------------------------------------------- | ----------------------- |
| **Package**          | `@web3auth/modal` + adapters                | `@web3auth/modal` only  |
| **Authentication**   | `OpenloginAdapter` required                 | Built-in                |
| **Chain Config**     | Manual `chainConfig` + `privateKeyProvider` | Dashboard configuration |
| **External Wallets** | Manual adapter setup                        | Automatic detection     |
| **Branding**         | `uiConfig` + `OpenloginAdapter` whiteLabel  | Dashboard configuration |
| **ID token**         | `authenticateUser()`                        | `getIdentityToken()`    |

## Benefits of v10 migration

1. **Unified architecture:** Single package handles all 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. Remove adapter configurations and use the unified SDK.
3. Configure your chains and branding on the Web3Auth Developer Dashboard.
4. Update method names (`authenticateUser` → `getIdentityToken`).
5. Test your application with the new unified architecture.