> For the complete documentation index, see [llms.txt](/llms.txt).

# 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[​](#ai-assisted-migration "Direct link to AI-assisted migration")

For the best results, install the MetaMask Embedded Wallets **skill** and **MCP server** before you migrate. See [Build with AI](/embedded-wallets/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://metamask-docs-git-ew-v11-consensys-ddffed67.vercel.app/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[​](#install-v8 "Direct link to 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:

- Bare React Native
- Expo

- npm
- Yarn
- pnpm
- Bun

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

```

```
yarn add @toruslabs/react-native-web-browser react-native-encrypted-storage

```

```
pnpm add @toruslabs/react-native-web-browser react-native-encrypted-storage

```

```
bun add @toruslabs/react-native-web-browser react-native-encrypted-storage

```

- npm
- Yarn
- pnpm
- Bun

```
npm install expo-web-browser expo-secure-store

```

```
yarn add expo-web-browser expo-secure-store

```

```
pnpm add expo-web-browser expo-secure-store

```

```
bun add expo-web-browser expo-secure-store

```

Run `npx expo prebuild` before building native code.

Register `{scheme}://auth` on the [Embedded Wallets dashboard](https://developer.metamask.io).

## Breaking changes[​](#breaking-changes "Direct link to Breaking changes")

Apply the sections below that match your current version. If you're already on v7, focus on the [v8 changes](#v8-changes).

### Storage parameter (from v4)[​](#storage-parameter-from-v4 "Direct link to Storage parameter (from v4)")

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

- Bare React Native
- Expo

```
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`,
})

```

```
import Web3Auth, { WEB3AUTH_NETWORK } from '@web3auth/react-native-sdk'
import * as WebBrowser from 'expo-web-browser'
import * as SecureStore from 'expo-secure-store'

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

```

### `login()` return type (from v4)[​](#login-return-type-from-v4 "Direct link to 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)[​](#whitelabel-configuration-from-v5 "Direct link to Whitelabel configuration (from v5)")

`WhiteLabelData` field names changed:

| v4 and earlier | v5 and later                      |
| -------------- | --------------------------------- |
| name           | appName                           |
| dark           | mode ('light', 'dark', or 'auto') |

New optional fields include `appUrl`, `useLogoLoader`, `tncLink`, and `privacyPolicy`. See [Whitelabel](/embedded-wallets/sdk/react-native/advanced/whitelabel/).

### Crypto polyfills (from v6)[​](#crypto-polyfills-from-v6 "Direct link to 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](/embedded-wallets/troubleshooting/metro-issues/) if the bundler fails.

### v8 changes[​](#v8-changes "Direct link to v8 changes")

#### Network enum[​](#network-enum "Direct link to Network enum")

Replace `OPENLOGIN_NETWORK` with `WEB3AUTH_NETWORK`:

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

network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,

```

#### Mandatory `privateKeyProvider`[​](#mandatory-privatekeyprovider "Direct link to 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[​](#connection-status "Direct link to 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[​](#redirect-url "Direct link to Redirect URL")

Update the redirect URL pattern:

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

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

```

## Summary table[​](#summary-table "Direct link to Summary table")

| Area            | v3 and earlier    | v4–v7                           | v8                          |
| --------------- | ----------------- | ------------------------------- | --------------------------- |
| Constructor     | 2 args            | 3 args (Storage)                | 3 args + privateKeyProvider |
| Network enum    | OPENLOGIN_NETWORK | OPENLOGIN_NETWORK               | WEB3AUTH_NETWORK            |
| Session check   | privKey           | privKey                         | connected                   |
| Provider setup  | Manual            | setupProvider()                 | web3auth.provider           |
| Redirect URL    | ://openlogin      | ://openlogin                    | ://auth                     |
| Crypto polyfill | crypto-browserify | react-native-quick-crypto (v6+) | react-native-quick-crypto   |
| Whitelabel name | name              | appName (v5+)                   | appName                     |

## Next steps[​](#next-steps "Direct link to Next steps")

- [React Native SDK get started](/embedded-wallets/sdk/react-native/)
- [Build with AI](/embedded-wallets/build-with-ai/) for ongoing integration help
- [Release notes](https://github.com/Web3Auth/web3auth-react-native-sdk/releases)