React Native Quickstart

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.

Get started with Dynamic’s React Native SDK to add embedded wallets, multi-chain support, and flexible authentication (email, social login, passkeys) to your mobile app in just a few lines.

Before you start: You’ll need Node.js 18+ and a Dynamic environment ID from the Dynamic dashboard.

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.

Agent-friendly

Add the Dynamic docs MCP to your AI editor first — your agent can then query the docs directly.

Cursor

Click here to add the MCP to Cursor.

Claude Code

claude mcp add --transport http dynamic https://www.dynamic.xyz/docs/mcp

Codex

codex mcp add dynamic --url https://www.dynamic.xyz/docs/mcp

Other

If your editor or agent supports remote HTTP MCP, add a server that points at https://www.dynamic.xyz/docs/mcp. The exact steps depend on the product; use its MCP documentation for URL-based or HTTP transport setup.

Copy this prompt into your LLM (e.g. Claude, ChatGPT, Cursor) to implement Dynamic in your React Native app.

# React Native SDK Quickstart

## Purpose and Usage

This document provides structured quickstart information for the Dynamic React Native SDK. It is designed to be consumed by LLMs to generate accurate installation commands and code examples based on user requirements.

> **Architecture note:** The React Native SDK uses a client-based architecture with extensions — NOT the provider-based architecture of the React SDK. Do NOT use `DynamicContextProvider`, `DynamicWidget`, or any other React SDK patterns here. They are different SDKs.

**How to use this document:**

**BEFORE WRITING ANY CODE**, ask the user which path they want:

> "Would you like a **Quick start** (Expo managed workflow + EVM, zero configuration — recommended if you're just getting started) or a **Custom setup** (choose your workflow, chains, passkeys, and account abstraction)?"

Do not proceed until the user has answered. Do not assume a path.

---

## Quick Start Path

> Use this path when the user chooses Quick start. Execute every step in order. Do not skip steps. Do not ask configuration questions.

**Stack:** Expo managed workflow + npm + EVM only + no passkeys + no ZeroDev

### Step 1 — Prerequisites

Tell the user:
- Node.js 18+ is required
- A Dynamic environment ID is required — get one at https://app.dynamic.xyz/dashboard/developer
- **This SDK is NOT compatible with Expo Go.** You must use a development build or EAS Build. If the user is using Expo Go, stop and inform them before proceeding.
- Test on a real device early — some features (passkeys, global wallets) do not work in simulators

Ask the user for their environment ID before proceeding.

### Step 2 — Scaffold the project

```bash
pnpm dlx create-expo-app my-app --template blank-typescript
cd my-app
```

### Step 3 — Install

Install all required packages explicitly. Missing peer dependencies cause runtime errors, not build errors — install all of them.

```bash
pnpm add @dynamic-labs/client @dynamic-labs/react-native-extension @dynamic-labs/viem-extension @dynamic-labs/react-hooks
```

> **pnpm build scripts:** pnpm v10 suppresses build scripts by default. Add the following to your `package.json` before installing to avoid native module issues:
> ```json
> "pnpm": { "onlyBuiltDependencies": ["@react-native-community/cli", "react-native", "esbuild"] }
> ```

### Step 4 — Prebuild (required — native modules)

The SDK relies on native modules (`react-native-webview`, `expo-secure-store`). You must rebuild the native layer after installing.

```bash
npx expo prebuild
```

> **CocoaPods UTF-8 error (macOS):** If `pod install` fails with `Unicode Normalization not appropriate for ASCII-8BIT`, run the following and retry:
> ```bash
> export LANG=en_US.UTF-8
> npx expo prebuild
> ```

Then run your app:
```bash
LANG=en_US.UTF-8 npx expo run:ios
# or
LANG=en_US.UTF-8 npx expo run:android
```

> **Warning:** Do not use `npx expo start` with Expo Go after this step — it will not work. Always use `expo run:ios` / `expo run:android` or a development build.

### Step 5 — Initialize the client

Create a `client.ts` file at the project root:

```typescript
import { createClient } from '@dynamic-labs/client';
import { ReactNativeExtension } from '@dynamic-labs/react-native-extension';
import { ViemExtension } from '@dynamic-labs/viem-extension';

export const dynamicClient = createClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  appLogoUrl: 'https://demo.dynamic.xyz/favicon-32x32.png',
  appName: 'My App',
  appOrigin: 'http://localhost:8081', // Required — use http://localhost:8081 for local Expo development
})
  .extend(ReactNativeExtension())
  .extend(ViemExtension());
```

> **`appOrigin` is required.** This must be set to your app's domain. It is used for MPC wallet operations and passkey configuration. The quickstart will not work without it.

### Step 6 — Add the WebView to your app

Open `App.tsx` (or `App.js` if your project uses JavaScript) and replace the contents:

```typescript
// App.tsx
import { SafeAreaView, Text } from 'react-native';
import { dynamicClient } from './client';

export default function App() {
  return (
    <>
      <dynamicClient.reactNative.WebView />
      <SafeAreaView>
        <Text>Hello from Dynamic!</Text>
      </SafeAreaView>
    </>
  );
}
```

### Step 7 — Read wallet state in a component

Use `useReactiveClient` from `@dynamic-labs/react-hooks` to reactively access client state in React components:

```typescript
import { useReactiveClient } from '@dynamic-labs/react-hooks';
import { dynamicClient } from './client';

export function WalletInfo() {
  const { wallets } = useReactiveClient(dynamicClient);
  const wallet = wallets[0];

  if (!wallet) return null;

  return <Text>Address: {wallet.address}</Text>;
}
```

### Step 8 — Dashboard configuration checklist

Before testing, verify these settings in your Dynamic dashboard at https://app.dynamic.xyz:

1. **Chains enabled** — go to **Chains & Networks** and enable EVM
2. **Embedded wallets enabled** — go to **Wallets** and enable embedded wallets
3. **Login method enabled** — go to **Sign-in Methods** and enable at least one (e.g. email OTP)
4. **CORS origin allowlisted** — go to **Security → Allowed Origins** and add your app's origin (e.g. `http://localhost:8081`)
5. **Deeplink URL registered** — go to **Security → Deeplink URLs** and add your app's deeplink scheme (required for social login and OAuth flows). See https://docs.dynamic.xyz/react-native/reference/deeplink-urls for setup instructions.

---

## Custom Setup Path

> Use this path when the user chooses Custom setup. Ask ALL questions below before generating any code.

**Questions to ask the user:**

1. Which workflow are you using? (Expo managed, EAS Build, bare React Native)
2. Which package manager do you prefer? (npm, yarn, pnpm, bun, expo)
3. Which chains do you want to support? (EVM, SVM, Sui — one or more)
4. Do you want to enable passkeys?
5. If EVM: do you want to enable Account Abstraction (ZeroDev)?

**Only after receiving answers**, use the sections below to generate the correct setup.

### Package Manager Commands
- `npm`: `npm i`
- `yarn`: `yarn add`
- `pnpm`: `pnpm add`
- `bun`: `bun add`
- `expo`: `npx expo install`

### Package Mapping

Always install all of the following explicitly — missing peer dependencies cause runtime errors, not build errors.

- Core (always required): `@dynamic-labs/client`
- React Native extension (always required): `@dynamic-labs/react-native-extension`
- EVM: `@dynamic-labs/viem-extension`
- SVM: `@dynamic-labs/solana-extension`
- Sui: `@dynamic-labs/sui-extension`
- ZeroDev (EVM only): `@dynamic-labs/zerodev-extension` + `events`

### Prebuild / Native Linking

Always required after install — the SDK relies on native modules.

- **Expo managed**: `npx expo prebuild` → `npx expo run:ios` or `npx expo run:android`
- **EAS Build**: native modules linked automatically — run `eas build --profile <your-profile> --platform all`
- **Bare React Native**: `cd ios && pod install && cd ..` → rebuild with Xcode or `npx react-native run-ios` / `npx react-native run-android`

> **Warning:** This SDK is NOT compatible with Expo Go. Always use a development build or EAS Build.

### Extension Mapping
- EVM → `ViemExtension` from `@dynamic-labs/viem-extension`
- SVM → `SolanaExtension` from `@dynamic-labs/solana-extension`
- Sui → `SuiExtension` from `@dynamic-labs/sui-extension`
- ZeroDev → `ZeroDevExtension` from `@dynamic-labs/zerodev-extension`

### Client Initialization

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

export const dynamicClient = createClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  appLogoUrl: 'https://demo.dynamic.xyz/favicon-32x32.png',
  appName: 'My App',
  appOrigin: 'https://YOUR-DOMAIN.com', // Required
})
  .extend(ReactNativeExtension({PASSKEY_CONFIG}))
  .extend({CHAIN_EXTENSIONS});
```

**Passkeys enabled:**
```typescript
ReactNativeExtension({ appOrigin: 'https://YOUR-DOMAIN.com' })
```

**Passkeys disabled:**
```typescript
ReactNativeExtension()
```

### WebView (required)

Always include `<dynamicClient.reactNative.WebView />` at the root of your component tree. Without it, the SDK's UI and auth flows will not function.

### Reactive State in Components

Use `useReactiveClient` from `@dynamic-labs/react-hooks` to access client state reactively in React components. Do NOT use React SDK hooks (`useDynamicContext`, etc.) — they do not exist in this SDK.

```typescript
import { useReactiveClient } from '@dynamic-labs/react-hooks';
import { dynamicClient } from './client';

const { wallets } = useReactiveClient(dynamicClient);
```

### TODOs for custom config

**When passkeys are enabled:**
```typescript
// TODO: Complete passkey setup — https://docs.dynamic.xyz/react-native/reference/setup-passkey
```

**When ZeroDev is enabled:**
```typescript
// TODO: Check for file resolution error fix — https://docs.dynamic.xyz/react-native/reference/wallets/account-abstraction#resolve-file-resolution-error-optional
```

**When social login is needed:**
```typescript
// TODO: Configure deeplink URLs — https://docs.dynamic.xyz/react-native/reference/deeplink-urls
```

### Valid Chain Combinations
- Any single chain or combination of EVM, SVM, and Sui is valid
- ZeroDev only applies when EVM is selected
- At least one chain must be selected

### Documentation
All docs for this SDK: https://docs.dynamic.xyz (paths starting with `/react-native/`)
Environment ID: https://app.dynamic.xyz/dashboard/developer/api

---

## Critical Reference

| Correct | Incorrect | Notes |
|---|---|---|
| `createClient().extend(ReactNativeExtension())` | `DynamicContextProvider` / `DynamicWidget` | React Native uses client + extensions, not providers |
| `useReactiveClient(dynamicClient)` | `useDynamicContext()` | React SDK hooks do not exist in this SDK |
| `<dynamicClient.reactNative.WebView />` | Omitting WebView | Required in component tree — auth flows will silently fail without it |
| `appOrigin: 'https://your-domain.com'` | Omitting `appOrigin` | Required field — wallet operations will fail without it |
| `npx expo run:ios` / `npx expo run:android` | `npx expo start` with Expo Go | Expo Go does not support custom native modules |
| Install all packages explicitly | Rely on transitive deps | Missing peer deps cause runtime errors, not build errors |

---

## Building a headless integration?

If you're building without the Dynamic Widget, see the [Authentication screens](/react-native/authentication-methods/headless-authentication) for a full list of screens your app needs to handle.

---

## Step-Up Authentication

**Required before accepting the `2026_04_01` API version** — verify your
minimum API version in [Dashboard > Developers > API & SDK Keys](https://app.dynamic.xyz/dashboard/developer/api).

The SDK provides built-in step-up UI via
`dynamicClient.stepUpAuth.promptStepUpAuth`. **If building a headless/custom
UI, you must handle step-up authentication manually** — check requirements
with `isStepUpRequired` and call the appropriate prompt or individual verify
method yourself.

See [Step-up authentication](/react-native/authentication-methods/step-up-auth/overview) for the full implementation guide.

---

## Device Registration

**Required before accepting the `2026_04_01` API version** — verify your
minimum API version in [Dashboard > Developers > API & SDK Keys](https://app.dynamic.xyz/dashboard/developer/api).

If using Dynamic's built-in UI (default), device registration is handled
automatically — no code required. **If building a headless/custom UI**
(`deviceRegistrationModal: { enabled: false }`), **you must manually check
whether the current device needs registration and handle the completion
event yourself.**

Full guide: https://docs.dynamic.xyz/react-native/authentication-methods/device-registration

---

## Troubleshooting

### 1 — App crashes immediately after install
Native modules were not linked. Run `npx expo prebuild` and rebuild with `npx expo run:ios` or `npx expo run:android`. Do not use Expo Go.

### 2 — Auth flow does nothing / WebView not showing
`<dynamicClient.reactNative.WebView />` is missing from the component tree. Add it at the root level of your app.

### 3 — Wallet creation fails or returns no wallet
Check the dashboard: embedded wallets must be enabled under **Wallets**, chains must be enabled under **Chains & Networks**, and the app origin must be allowlisted under **Security → Allowed Origins**.

### 4 — Social login / OAuth redirects fail
Deeplink URLs must be registered in the Dynamic dashboard under **Security → Deeplink URLs**. Your app URL scheme must also be configured in `app.json`. See https://docs.dynamic.xyz/react-native/reference/deeplink-urls.

### 5 — Passkey errors
Passkeys require additional native setup beyond installing the package and setting `appOrigin`. Follow the full passkey setup guide: https://docs.dynamic.xyz/react-native/reference/setup-passkey. Passkeys also do not work in simulators — test on a real device.

### 6 — Wrong hook or import errors
Do not use React SDK imports (`@dynamic-labs/sdk-react-core`, `useDynamicContext`, etc.) in a React Native project. The React Native SDK is a separate package with a different API surface. Some docs pages under the React Native section may show React SDK patterns for certain chains — those examples are not correct for the React Native client-based architecture.

If the issue persists, check https://docs.dynamic.xyz/react-native/reference/troubleshooting and https://docs.dynamic.xyz/overview/troubleshooting/general.

Manual

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 (managed)

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.

EAS Build

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.

Bare React Native

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.

Use the client and its modules; use useReactiveClient from @dynamic-labs/react-hooks when you need reactive state in components.

appOrigin is a mandatory field in the Dynamic config. Make sure to set it to your app’s origin URL when initializing the SDK.

Polyfills

Please refer to the Polyfills section for information on how to set up necessary polyfills.

Setup Deeplink URLs

In order to use most of the React Native features (such as social connections), you will first have to set up the list of mobile deeplink URLs Dynamic may use to redirect back to your app.

For detailed instructions on configuring deeplinks, please refer to our Deeplink URLs guide.

Next Steps

Step-up authentication and device registration are required before accepting the 2026_04_01 API version. If you have a headless integration, you must implement both manually. See the upgrade guide.

• Step-up authentication
• Device registration

Building without the Dynamic Widget? See the Authentication screens for a full list of screens your app needs to handle.