react-native-extension

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 package that gives access to an Extension that allows adding react native support to our client.

Functions

ReactNativeExtension method

ReactNativeExtension(props?: ReactNativeExtensionProps): Extension<IReactNativeExtension>

A method that, when passed to the client instance, injects the following modules into it:

reactNative module

Provides access to the webview that renders our SDK in the background of your app.

The client itself is only an interface to our SDK, so it must be rendered to your app in order for the client to work.

Property	Type	Description
WebView	() => JSX.Element	The react native component that renders our SDK in the background.

Types

ReactNativeExtensionProps type

Properties which you can pass to the extension.

Param	Type	Description
appOrigin	string?	The web origin of your app (e.g. https://demo.dynamic.xyz). Used for SIWE messages, fetch Origin headers, and passkey operations. Deep link redirects use the auto-configured redirectUrl from expo-linking.
webviewUrl	string?	The URL to load in the WebView. Defaults to https://webview.dynamicauth.com/${version}.
webviewDebuggingEnabled	boolean?	Enables debugging in the WebView (e.g. Safari Web Inspector on iOS, chrome://inspect on Android). Useful in development.
embeddedWebView	boolean?	When true on iOS / Android, the SDK hosts the webview-controller in a native overlay window outside the React Native view tree. See Embedded WebView mode. Defaults to false. Available from v4.82.0.
webviewLoad	WebViewLoadOptions?	Tunable budgets for the webview load engine (attempt count and per-phase timeouts). Applies to both webview paths. See Tuning and monitoring the WebView load.

type ReactNativeExtensionProps = {
  appOrigin?: string
  webviewUrl?: string
  webviewDebuggingEnabled?: boolean
  embeddedWebView?: boolean
  webviewLoad?: WebViewLoadOptions
}

type WebViewLoadOptions = {
  maxAttempts?: number
  pageLoadTimeoutMs?: number
  firstAttemptPageLoadTimeoutMs?: number
  sdkReadyTimeoutMs?: number
}

Embedded WebView mode

Available from v4.82.0.

When embeddedWebView is set to true, the SDK renders its webview-controller inside a dedicated native overlay (WKWebView on iOS, android.webkit.WebView on Android) owned by a separate UI window outside the React Native view tree.

This isolates the webview from RN re-renders, navigation transitions, and other lifecycle events that can otherwise tear the webview down — which is useful for apps with complex navigation stacks where the wallet session needs to survive aggressive remounts.

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

When embeddedWebView is true, the component returned at dynamicClient.reactNative.WebView becomes a no-op — do not render it. The native overlay is created lazily and retained for the process lifetime.

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

Embedded mode runs the same bounded-retry load engine as the standard react-native-webview path, so transient failures are retried automatically and you can observe progress and trigger a manual retry through the same API — see Tuning and monitoring the WebView load. Once every attempt is exhausted, the failure surfaces as core.initialization.error with WebViewFailedToLoadError — treat the SDK as un-initialised and react accordingly.

IReactNativeExtension type

Type of the react native extension.

type IReactNativeExtension = {
  reactNative: {
    WebView: () => JSX.Element
  }
}