For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

React Native SDK v8 Migration Guide

This guide upgrades Embedded Wallets React Native SDK integrations from v3 through v7 directly to v8.

AI-assisted migration​

For the best results, install the MetaMask Embedded Wallets skill and MCP server before you migrate. See Build with AI for setup (npx skills add web3auth/skill and MCP at https://mcp.web3auth.io).

Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, Antigravity, or similar):

Migrate my MetaMask Embedded Wallets React Native (@web3auth/react-native-sdk) project to v8.

Before changing code:
1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference).
2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/react-native-v8
3. Detect my workflow (bare React Native or Expo) and current SDK version from package.json.

Then migrate my codebase directly to v8:
- Update @web3auth/react-native-sdk to ^8.0.0 and @web3auth/ethereum-provider to ^9.3.0.
- Replace OPENLOGIN_NETWORK with WEB3AUTH_NETWORK.
- Add mandatory privateKeyProvider (EthereumPrivateKeyProvider) to the Web3Auth constructor.
- Replace web3auth.privKey checks with web3auth.connected; use web3auth.provider directly.
- Update redirectUrl from {scheme}://openlogin to {scheme}://auth.
- Configure react-native-quick-crypto in globals.js and metro.config.js.
- Update WhiteLabelData (appName, mode) if whitelabeling is configured.
- Do not change my Client ID or Sapphire network unless I ask — that would change wallet addresses.

After migrating, list every file you changed and any manual dashboard steps I still need to do.
tip

Use planning mode (where available) for the initial prompt. Review the plan before generating code; config mistakes can change wallet addresses in production.

Install v8​

Update dependencies in package.json:

"@web3auth/react-native-sdk": "^8.0.0",
"@web3auth/ethereum-provider": "^9.3.0",
"react-native-quick-crypto": "^0.7.6"

Install helper modules for your workflow:

npm install @toruslabs/react-native-web-browser react-native-encrypted-storage

Register {scheme}://auth on the Embedded Wallets dashboard.

Breaking changes​

Apply the sections below that match your current version. If you're already on v7, focus on the v8 changes.

Storage parameter (from v4)​

The Web3Auth constructor requires a Storage implementation as the second argument:

import Web3Auth, { WEB3AUTH_NETWORK } from '@web3auth/react-native-sdk'
import * as WebBrowser from '@toruslabs/react-native-web-browser'
import EncryptedStorage from 'react-native-encrypted-storage'

const web3auth = new Web3Auth(WebBrowser, EncryptedStorage, {
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID',
  network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  redirectUrl: `${scheme}://auth`,
})

login() return type (from v4)​

login() returns Promise<void>. Use getters after login:

  • web3auth.privKey — secp256k1 private key
  • web3auth.ed25519Key — Ed25519 private key
  • web3auth.userInfo() — user profile

Whitelabel configuration (from v5)​

WhiteLabelData field names changed:

v4 and earlierv5 and later
nameappName
darkmode ('light', 'dark', or 'auto')

New optional fields include appUrl, useLogoLoader, tncLink, and privacyPolicy. See Whitelabel.

Crypto polyfills (from v6)​

Install react-native-quick-crypto and update Metro to resolve crypto to it:

config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (moduleName === 'crypto') {
    return context.resolveRequest(context, 'react-native-quick-crypto', platform)
  }
  return context.resolveRequest(context, moduleName, platform)
}

Update globals.js:

import { install } from 'react-native-quick-crypto'

install()

global.location = { protocol: 'file:' }
global.process.version = 'v16.0.0'
if (!global.process.version) {
  global.process = require('process')
}
process.browser = true

Import globals in your entry point. For Expo, also import @ethersproject/shims and @expo/metro-runtime. See Metro troubleshooting if the bundler fails.

v8 changes​

Network enum​

Replace OPENLOGIN_NETWORK with WEB3AUTH_NETWORK:

import { WEB3AUTH_NETWORK } from '@web3auth/react-native-sdk'

network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,

Mandatory privateKeyProvider​

Pass EthereumPrivateKeyProvider in the constructor:

import { EthereumPrivateKeyProvider } from '@web3auth/ethereum-provider'
import { CHAIN_NAMESPACES } from '@web3auth/base'

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

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

const web3auth = new Web3Auth(WebBrowser, EncryptedStorage, {
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID',
  network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  redirectUrl: `${scheme}://auth`,
  privateKeyProvider: ethereumPrivateKeyProvider,
})

Connection status​

Replace privKey session checks with connected. Use web3auth.provider directly — setupProvider() is no longer needed:

if (web3auth.connected) {
  setProvider(web3auth.provider)
  setLoggedIn(true)
}

Redirect URL​

Update the redirect URL pattern:

// Before
const redirectUrl = `${scheme}://openlogin`

// After
const redirectUrl = `${scheme}://auth`

Summary table​

Areav3 and earlierv4–v7v8
Constructor2 args3 args (Storage)3 args + privateKeyProvider
Network enumOPENLOGIN_NETWORKOPENLOGIN_NETWORKWEB3AUTH_NETWORK
Session checkprivKeyprivKeyconnected
Provider setupManualsetupProvider()web3auth.provider
Redirect URL://openlogin://openlogin://auth
Crypto polyfillcrypto-browserifyreact-native-quick-crypto (v6+)react-native-quick-crypto
Whitelabel namenameappName (v5+)appName

Next steps​

On this page