> ## Documentation Index
> Fetch the complete documentation index at: https://starkware-9575960b-starkzapv4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native Integration

> Set up StarkZap in React Native/Expo projects with starkzap-native and Metro configuration

## Overview

Use `starkzap-native` when integrating StarkZap in React Native/Expo apps.
It re-exports the SDK API and adds a Metro helper (`starkzap-native/metro`) that handles ESM/CJS resolver compatibility for `starknet` and its dependencies, and hoists your polyfills to run before the app entry.

## 1) Install Packages

Install the React Native package and the one polyfill every StarkZap flow needs:

```bash theme={null}
npm install starkzap-native
npm install fast-text-encoding
```

Install the rest **only for the features you actually use** — each is reached by a specific code path, not by every flow:

```bash theme={null}
# Cartridge sessions, paymaster / outside-execution (SNIP-9), random key generation
npm install react-native-get-random-values

# Ethereum bridge routes — pulls in ethers, which needs Buffer + crypto shims
npm install ethers buffer @ethersproject/shims

# Solana bridging — required for any Solana route
npm install @solana/web3.js

# Additionally, only if you use the Hyperlane Solana routes
npm install @hyperlane-xyz/sdk @hyperlane-xyz/registry @hyperlane-xyz/utils

# STRK20 privacy pool with OHTTP on. Supplies the `crypto.subtle` Hermes lacks
npm install react-native-quick-crypto react-native-nitro-modules react-native-quick-base64
```

## 2) Configure Metro

Set up Metro once and wrap your config with `withStarkzap`:

```javascript theme={null}
// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const { withStarkzap } = require("starkzap-native/metro");

const config = getDefaultConfig(__dirname);

// Optional: add your own resolver overrides before wrapping.
module.exports = withStarkzap(config);
```

<Info>
  `withStarkzap` handles resolver compatibility for StarkZap dependencies and hoists your polyfills to run first. It does **not** import the polyfills for you — do that at your app entry (next step).
</Info>

## 3) Load polyfills at your app entry

`withStarkzap` can only run polyfills that are in Metro's module graph — it reorders them so they run first, but it cannot import them for you. Import the ones your app needs **once**, at your entry point (e.g. `index.js` or your root layout), before any StarkZap code runs.

Each polyfill exists for a specific reason, so import only what your app actually uses:

| Polyfill | Provides | Needed by |
| - | - | - |
| `fast-text-encoding` | `TextEncoder` / `TextDecoder` | **Every flow** — `starknet` hashes an entrypoint selector via `TextEncoder` on every contract read/write (`getSelectorFromName`), and decodes returned strings/byte-arrays |
| `react-native-get-random-values` | `crypto.getRandomValues` | **Cartridge** sessions, **paymaster / outside-execution** (SNIP-9) nonces, and random key generation. Deterministic signing and read calls do **not** need it |
| `buffer` (+ set the global) | `Buffer` | **Bridge only** — `ethers` and the Solana bridge code |
| `@ethersproject/shims` | ethers crypto/random shims | **Bridge only** — `ethers` (v6) used by the Ethereum bridge. The shims package is itself v5-era, but it is what supplies the missing React Native crypto globals |
| `react-native-quick-crypto` | `crypto.subtle` | **STRK20 privacy with OHTTP only.** The OHTTP transport needs WebCrypto. Hermes has none, and `react-native-get-random-values` supplies only `getRandomValues` |

Required for every app:

```typescript theme={null}
// polyfills.ts — imported first at your app entry
import "fast-text-encoding";
```

Add if you use Cartridge, the paymaster, or generate keys:

```typescript theme={null}
import "react-native-get-random-values";
```

Add if you use the bridge features:

```typescript theme={null}
import { Buffer } from "buffer";
import "@ethersproject/shims";

if (!globalThis.Buffer) globalThis.Buffer = Buffer;
```

Add this if you use the [STRK20 privacy pool](/build/starkzap/privacy/strk20) with OHTTP on. Take only `subtle`. The package's own `install()` replaces the whole `crypto` global, including the `getRandomValues` installed above for `starknet`:

```typescript theme={null}
if (!globalThis.crypto.subtle) {
  const { subtle } = require("react-native-quick-crypto");
  Object.defineProperty(globalThis.crypto, "subtle", {
    value: subtle,
    configurable: true,
  });
}
```

<Note>
  Use `require` inside the guard, not a top-level `import`. The package loads native
  modules at import time, so an unconditional import crashes where those modules
  are absent, such as Expo Go. It needs a dev build (`npx expo run:android`). In
  an existing native project, run `npx expo prebuild` again so the C++ module is
  linked.
</Note>

Then import that file as the very first line of your entry:

```typescript theme={null}
// app entry (e.g. app/_layout.tsx)
import "./polyfills";
```

If you skip `fast-text-encoding`, `starknet` crashes on the first contract call (`TextEncoder is not defined`) — `starkzap-native` warns in the console when it's absent. Skipping `react-native-get-random-values` surfaces a clear `crypto.getRandomValues must be defined` only when a Cartridge/paymaster/keygen path runs.

## 4) Initialize the SDK

Import from `starkzap-native` and use the same onboarding APIs as web:

```typescript theme={null}
import { StarkZap, OnboardStrategy, StarkSigner } from "starkzap-native";

const sdk = new StarkZap({ network: "sepolia" });

const { wallet } = await sdk.onboard({
  strategy: OnboardStrategy.Signer,
  account: { signer: new StarkSigner("0xYOUR_PRIVATE_KEY") },
  deploy: "if_needed",
});
```

For Privy-based onboarding, see [Privy Integration](/build/starkzap/integrations/privy).

## 5) Cartridge (native session)

When your `starkzap-native` version supports it, you can onboard with **Cartridge** using an in-app browser / deep-link **session** flow (not the web `@cartridge/controller` popup).

1. **Register** the native Cartridge adapter **once** at app startup, before `connectCartridge()` or `onboard({ strategy: OnboardStrategy.Cartridge })`. Exact export names depend on your SDK version (for example `registerCartridgeTsAdapter` / `registerCartridgeNativeAdapter`).
2. Pass **policies** and/or a Cartridge **preset** that resolves policies for your chain (same concepts as [Cartridge Controller](/build/starkzap/integrations/cartridge-controller)).
3. Align `rpcUrl` / `chainId` (or `network`) on `new StarkZap({ ... })` with the session and paymaster you target.
4. **Deploy:** native Cartridge flows often default to **`deploy: "never"`** or recommend it when deployment semantics differ from the browser Controller. Pass **`deploy: "if_needed"`** explicitly if you need core-style deployment checks.
5. **Fees:** sponsored execution on native is tied to the session wallet (commonly **`feeMode: { type: "paymaster" }`** only for matching policy paths, without `gasToken`).

See [Cartridge Controller](/build/starkzap/integrations/cartridge-controller) for policy and paymaster behavior, and the `examples/tic-tac-toe` app in the [Starkzap repository](https://github.com/keep-starknet-strange/starkzap) when available for a full Expo reference.

## 6) External Wallet Providers (Optional)

If your app uses WalletConnect/Reown for external wallets, initialize its RN compatibility layer at app startup:

```typescript theme={null}
import "@walletconnect/react-native-compat";
```

Then pass the resulting providers into StarkZap external wallet adapters as described in [Bridging](/build/starkzap/bridging#connect-external-wallets).

<Warning>
  If `connectCartridge` or Cartridge onboarding throws **not implemented**, your installed `starkzap-native` build does not ship the native adapter yet — upgrade to a version that documents native Cartridge, or use **Signer** / **Privy** until then.
</Warning>

## Next Steps

* [Quick Start](/build/starkzap/quick-start)
* [Connecting Wallets](/build/starkzap/connecting-wallets)
* [Bridging](/build/starkzap/bridging)
* [Troubleshooting](/build/starkzap/troubleshooting)
* [Examples](/build/starkzap/examples)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.