React Native Integration

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:

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:

# 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:

// 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);

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).

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:

// polyfills.ts — imported first at your app entry
import "fast-text-encoding";

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

import "react-native-get-random-values";

Add if you use the bridge features:

import { Buffer } from "buffer";
import "@ethersproject/shims";

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

Add this if you use the STRK20 privacy pool with OHTTP on. Take only subtle. The package’s own install() replaces the whole crypto global, including the getRandomValues installed above for starknet:

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

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.

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

// 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:

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.

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).

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).
Pass policies and/or a Cartridge preset that resolves policies for your chain (same concepts as Cartridge Controller).
Align rpcUrl / chainId (or network) on new StarkZap({ ... }) with the session and paymaster you target.
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.
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 for policy and paymaster behavior, and the examples/tic-tac-toe app in the Starkzap repository 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:

import "@walletconnect/react-native-compat";

Then pass the resulting providers into StarkZap external wallet adapters as described in Bridging.

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.

Getting Started

Configuration

Using LLMs

Modules

Privacy

Integrations

Examples

Reference

Overview

1) Install Packages

2) Configure Metro

3) Load polyfills at your app entry

4) Initialize the SDK

5) Cartridge (native session)

6) External Wallet Providers (Optional)

Next Steps

​Overview

​1) Install Packages

​2) Configure Metro

​3) Load polyfills at your app entry

​4) Initialize the SDK

​5) Cartridge (native session)

​6) External Wallet Providers (Optional)

​Next Steps

Overview

1) Install Packages

2) Configure Metro

3) Load polyfills at your app entry

4) Initialize the SDK

5) Cartridge (native session)

6) External Wallet Providers (Optional)

Next Steps