Adding React Native support

Recommended: JavaScript SDK for React Native

While this SDK is still supported, we recommend using newer JavaScript SDK, which is optimized for React Native, but also comes with a host of other benefits.

The way Dynamic integrates with React Native is by extending our client with the React Native Extension. This adds the reactNative module, which provides access to a webview component that must be rendered to your app.

Since our client was built with a modular approach, each extension must be installed as a separate package, so to keep the client’s package size to a minimum.

Installation

From v4.83.0 onwards, the React Native SDK requires Expo SDK 52 or later. @dynamic-labs/react-native-extension declares expo-modules-core: >=2.0.0 as a peer dependency, which is first satisfied by Expo SDK 52. Stay on v4.82.x if you need to support Expo SDK 50 or 51.

Simply run the following in your terminal:

expo
npm
yarn

Shell

npx expo install @dynamic-labs/react-native-extension react-native-webview expo-web-browser expo-linking expo-secure-store

Shell

npm install @dynamic-labs/react-native-extension react-native-webview expo-web-browser expo-linking expo-secure-store

Shell

yarn install @dynamic-labs/react-native-extension react-native-webview expo-web-browser expo-linking expo-secure-store

Prebuild (Expo) / Native linking

Since our SDK relies on native modules (e.g. react-native-webview, expo-secure-store), you need to rebuild the native layer of your app after installing.

Expo Go is not supported. Dynamic depends on native modules that are linked when you prebuild your app (for example with npx expo prebuild or an EAS/cloud build). Expo Go runs a generic prebuilt client and does not prebuild your project, so those native dependencies never make it into the binary you launch. Use a development build, EAS Build, or a bare React Native workflow instead.

Expo (managed)
EAS Build
Bare React Native

If you’re using Expo with a managed workflow, run:

Shell

npx expo prebuild

Then rebuild your app with npx expo run:ios or npx expo run:android.

If you’re using EAS Build, the native modules will be linked automatically during the cloud build. Simply run:

Shell

eas build --profile <your-profile> --platform all

Then install the resulting development build on your device or simulator.

If you’re using a bare React Native project, install the native dependencies:

Shell

cd ios && pod install && cd ..

Then rebuild your app using Xcode or npx react-native run-ios / npx react-native run-android.

Usage with React Native

First, extend your client with our extension:

import { ReactNativeExtension } from '@dynamic-labs/react-native-extension';

export const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
}).extend(ReactNativeExtension());

Next, render the webview injected into the client by the extension:

import { dynamicClient } from '<path to client file>';

export function App() {
  return (
    <>
      <dynamicClient.reactNative.WebView />

      <SafeAreaView>
        { ... }
      </SafeAreaView>
    </>
  )
}

You can read more about our react native package here.

Embedded WebView (native overlay)

Available from v4.82.0.

By default, the SDK renders its webview as a regular React Native component (via react-native-webview) that you mount in your app tree. If your app’s navigation aggressively unmounts and remounts screens — or you simply want the wallet session to be fully decoupled from your view tree — you can opt in to embedded WebView mode. Pass embeddedWebView: true to the extension:

import { createClient } from '@dynamic-labs/client'
import { ReactNativeExtension } from '@dynamic-labs/react-native-extension'

export const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
}).extend(
  ReactNativeExtension({
    appOrigin: 'https://your-app.example',
    embeddedWebView: true,
  }),
)

In this mode the SDK hosts the webview-controller inside a dedicated native overlay window (WKWebView on iOS, android.webkit.WebView on Android) owned outside the React Native view tree. The overlay is created lazily on first use and retained for the process lifetime.

When embeddedWebView is true, do not render dynamicClient.reactNative.WebView in your app — it resolves to a no-op component on the embedded path.

import { dynamicClient } from '<path to client file>';

export function App() {
  return (
    <SafeAreaView>
      { ... }
    </SafeAreaView>
  )
}

On platforms other than iOS / Android (e.g. web), the embeddedWebView flag is ignored and the standard react-native-webview path is used.

Caveats

Same load engine as the standard path. The embedded overlay runs the same bounded-retry load engine as the react-native-webview path, so a transient failure is retried automatically and you can observe progress and trigger a manual retry through the same API — see Tuning and monitoring the WebView load. When every attempt is exhausted, the failure surfaces as core.initialization.error with WebViewFailedToLoadError; treat the SDK as un-initialised in your error handler.
Singleton. Re-invoking ReactNativeExtension({ embeddedWebView: true }) (e.g. when you recreate the client with a different environmentId) re-binds the JS bridge to the same native overlay rather than creating a new one.
Debugging still works via webviewDebuggingEnabled: true (Safari Web Inspector on iOS, chrome://inspect on Android).

Tuning and monitoring the WebView load

Whichever WebView path you use, the SDK loads its webview through a bounded-retry engine: each load attempt is given a time budget, a transient failure (network drop, wedged CDN edge) is retried automatically after a short backoff, and the failure only becomes terminal once every attempt is exhausted. You can tune the budgets, observe the load in real time, and trigger a manual retry.

Tuning the load budgets

Pass a webviewLoad group to the extension to tune how long each attempt may take and how many attempts to make. Every field is optional — only tune these for pathological networks.

import { createClient } from '@dynamic-labs/client'
import { ReactNativeExtension } from '@dynamic-labs/react-native-extension'

export const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
}).extend(
  ReactNativeExtension({
    webviewLoad: {
      maxAttempts: 3,
      pageLoadTimeoutMs: 20000,
      firstAttemptPageLoadTimeoutMs: 10000,
      sdkReadyTimeoutMs: 20000,
    },
  }),
)

Field	Type	Default	Description
`maxAttempts`	`number?`	`3`	Total load attempts per cycle (the initial attempt plus automatic retries). `1` disables automatic retries — the first failure is terminal and your app owns recovery via `client.sdk.retry()`. Values are clamped into `[1, 10]` with a console warning.
`pageLoadTimeoutMs`	`number?`	`20000`	Max time (ms) an attempt may spend loading the page (waiting for the server’s response and for the page to finish).
`firstAttemptPageLoadTimeoutMs`	`number?`	`10000`	Fail-fast cap (ms) on the first attempt’s wait-for-response window only, so a wedged first load retries quickly instead of burning the full `pageLoadTimeoutMs`. It is a cap, never an extension — set it at or above `pageLoadTimeoutMs` to disable fail-fast. Values below 1s are clamped to 1s with a console warning.
`sdkReadyTimeoutMs`	`number?`	`20000`	Max time (ms) between the page finishing its load and the Dynamic SDK inside the webview signalling it is ready.

A misconfigured value warns and is clamped into its safe range — it never throws, so a config typo cannot crash SDK initialisation.

Observing the load state

client.sdk.loadState is a live snapshot of the load engine. Read it through useReactiveClient to re-render on every change:

import { useReactiveClient } from '@dynamic-labs/react-hooks'
import { Text } from 'react-native'

import { dynamicClient } from '<path to client file>'

export const LoadStatus = () => {
  const { sdk } = useReactiveClient(dynamicClient)
  const { status, attempt, maxAttempts } = sdk.loadState

  if (status === 'ready' || status === 'idle') return null

  return <Text>Connecting to Dynamic… (attempt {attempt}/{maxAttempts})</Text>
}

loadState has the following shape:

Field	Type	Description
`status`	`'idle' \| 'loading' \| 'waiting_to_retry' \| 'ready' \| 'failed'`	Lifecycle status of the load. A stable contract you can branch on. `waiting_to_retry` means the attempt failed and the next is waiting out its backoff.
`phase`	`string \| null`	The in-flight step of the current attempt while `loading`. Diagnostic only — do not branch on it, as the values may change between versions.
`attempt`	`number`	1-based counter of load attempts within the current cycle. `0` until the webview load controller has been registered.
`maxAttempts`	`number`	Total attempt budget of a cycle. `0` until the webview load controller has been registered.
`nextRetryAt`	`number \| null`	Wall-clock timestamp (ms) the pending retry is due at while `waiting_to_retry`, else `null`. Use it to render a countdown.
`error`	`Error \| null`	The terminal SDK initialization error while `failed` (proxies `client.sdk.error`), else `null`.

Outside React, subscribe to the loadStateChanged event instead:

const handleLoadStateChanged = (loadState) => {
  console.log('load state', loadState.status)
}

dynamicClient.sdk.on('loadStateChanged', handleLoadStateChanged)

// When you no longer need to listen
dynamicClient.sdk.off('loadStateChanged', handleLoadStateChanged)

Retrying a failed load

When status is failed, call client.sdk.retry() to start a fresh load cycle. It resolves with the load state of the next ready or failed transition. Calling it while waiting_to_retry skips the remaining backoff and retries immediately; in any other state it is a safe no-op.

import { useReactiveClient } from '@dynamic-labs/react-hooks'
import { Button, Text, View } from 'react-native'

import { dynamicClient } from '<path to client file>'

export const LoadRetry = () => {
  const { sdk } = useReactiveClient(dynamicClient)

  if (sdk.loadState.status !== 'failed') return null

  return (
    <View>
      <Text>Dynamic failed to load</Text>
      <Button title='Retry' onPress={() => void sdk.retry()} />
    </View>
  )
}

Set maxAttempts: 1 when you want your app to own the retry experience: the first failure becomes terminal immediately, and you drive recovery entirely through your own UI and client.sdk.retry().

Installation & Configuration

Authenticate

Wallets

Gasless

Chains & Networks

Users & Verified Credentials

Gating & Access Control

Integrations

React Native SDK Reference

Adding React Native support

Recommended: JavaScript SDK for React Native

Installation

Prebuild (Expo) / Native linking

Usage with React Native

Embedded WebView (native overlay)

Caveats

Tuning and monitoring the WebView load

Tuning the load budgets

Observing the load state

Retrying a failed load

Recommended: JavaScript SDK for React Native

​Installation

​Prebuild (Expo) / Native linking

​Usage with React Native

​Embedded WebView (native overlay)

​Caveats

​Tuning and monitoring the WebView load

​Tuning the load budgets

​Observing the load state

​Retrying a failed load

Installation

Prebuild (Expo) / Native linking

Usage with React Native

Embedded WebView (native overlay)

Caveats

Tuning and monitoring the WebView load

Tuning the load budgets

Observing the load state

Retrying a failed load