DEV Community: Farouq Seriki

OWASP Mobile Top 10 for React Native Fintech Apps: A Practical Implementation Checklist

Farouq Seriki — Sat, 16 May 2026 13:17:01 +0000

TL;DR

The OWASP Mobile Top 10 isn't abstract theory — it's the exact list pen testers use to fail your app. Here's the cheat sheet: M1 — stop storing tokens in AsyncStorage, use Keychain/Keystore. M2 — audit your node_modules before it audits you. M3 — biometric gates belong on every sensitive screen, not just login. M4 — parameterize your SQLite queries and validate deep links. M5 — SSL pin your public keys, not your certs, and always have a backup pin. M6 — your crash reporter is exfiltrating PII right now. M7 — enable Hermes, strip source maps, turn off debug mode. M8 — detect jailbreak/root but let your developers bypass it. M9 — encrypt local data with MMKV + Keychain-stored keys. M10 — Math.random() is not random; use expo-crypto.

Why This Matters Now

The OWASP Mobile Top 10 was updated in 2024 with a significant restructuring. "Insecure Data Storage" and "Insecure Communication" are still there, but the new list adds "Inadequate Supply Chain Security" (M2) — which feels like it was written specifically for the npm ecosystem — and "Insufficient Binary Protections" (M7), which targets exactly the kind of JavaScript-bundle-in-a-native-shell architecture that React Native uses.

If you're building a fintech app in React Native, you're a target. RN apps ship a JavaScript bundle that can be extracted, decompiled, and analyzed in minutes. Unlike Swift or Kotlin binaries, there's no compilation step that obfuscates your logic by default. An attacker with a rooted Android device can pull your APK, unzip it, and read your business logic in index.android.bundle — including any hardcoded API keys, endpoint URLs, or validation logic you thought was "server-side."

What does a failed security audit actually cost? I've seen three outcomes: App Store rejection during review (Apple has gotten aggressive about checking for jailbreak detection and SSL pinning in fintech apps), a pen test report with 15+ critical findings that delays launch by 2-3 months, or worse — a compliance failure that means you can't process payments at all. PCI DSS, SOC 2, and regional banking regulations all reference OWASP controls.

And the breaches are real. In 2018, British Airways lost data on 400,000 customers due to poor authentication and unsecured third-party scripts — the ICO fined them £20 million. In 2021, ParkMobile exposed 21 million users' data through a vulnerability in a third-party component. These aren't theoretical risks — they're financial and regulatory consequences that hit real companies.

The gap I keep seeing: everyone knows the names of these vulnerabilities. Blog posts explain what "insecure data storage" means. But almost nobody shows the actual TypeScript code. This article is the code.

The companion repository has every file referenced below: github.com/FastheDeveloper/owasp-rn-fintech

Every section includes screenshots from the interactive demo app so you can see these controls in action — not just read about them.

Project Setup

npx create-expo-app@latest owasp-rn-fintech --template blank-typescript
cd owasp-rn-fintech

# Secure storage & crypto
npx expo install expo-secure-store@15.x expo-crypto@15.x

# Biometrics
npx expo install expo-local-authentication@17.x

# SSL pinning
npm install react-native-ssl-public-key-pinning@1.2.x

# Encrypted local storage
npm install react-native-mmkv@4.x

# Local database
npx expo install expo-sqlite@16.x

# Jailbreak detection
npm install jail-monkey@3.x

Warning: react-native-ssl-public-key-pinning, react-native-mmkv, and jail-monkey require native modules. They won't work in Expo Go — you'll need a development build (npx expo prebuild + npx expo run:ios).

M1: Improper Credential Usage

What it means in React Native: Hardcoded API keys in your source code. Auth tokens stored in AsyncStorage (plaintext JSON files on disk). Secrets committed to your repo via .env files that aren't gitignored. Refresh tokens that never expire.

Real-World Incident: In 2016, Uber's breach exposed 57 million users' and drivers' personal data — names, emails, phone numbers, and 600,000 driver's license numbers. The root cause: Uber engineers had hardcoded AWS credentials in a private GitHub repository. Attackers used those credentials to access an S3 bucket containing the user database. Uber then paid the attackers $100,000 through their bug bounty program to delete the data and keep quiet — and didn't disclose the breach for over a year. Hardcoded credentials in source code is the #1 credential misuse pattern, and it applies equally to mobile apps: API keys in your React Native bundle, tokens in .env files committed to git, or secrets baked into your build config.

I audited a production fintech app recently and found this exact pattern:

// ❌ WRONG — This is what most RN apps do
// store/store.ts (actual production code)

import AsyncStorage from "@react-native-async-storage/async-storage";
import { persistReducer, persistStore } from "redux-persist";

const persistConfig = {
  key: "root",
  storage: AsyncStorage, // ← PLAINTEXT on disk
  whitelist: ["persisted", "auth"], // ← auth tokens persisted in plaintext
};

On a rooted Android device, that data lives at /data/data/com.yourapp/files/RCTAsyncLocalStorage/manifest.json. Every token, every piece of user state — plaintext. Even on iOS, if a user backs up their device unencrypted, those tokens are in the backup.

The fix has two parts: store credentials in Keychain/Keystore (hardware-encrypted), and implement session expiry so stolen tokens have a shelf life.

// src/security/secure-storage.ts

import * as SecureStore from "expo-secure-store";

const SECURE_STORE_OPTIONS: SecureStore.SecureStoreOptions = {
  keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
};

export const CredentialStore = {
  async setToken(key: string, value: string): Promise<void> {
    await SecureStore.setItemAsync(key, value, SECURE_STORE_OPTIONS);
  },

  async getToken(key: string): Promise<string | null> {
    return SecureStore.getItemAsync(key, SECURE_STORE_OPTIONS);
  },

  async deleteToken(key: string): Promise<void> {
    await SecureStore.deleteItemAsync(key);
  },

  async clearAll(keys: string[]): Promise<void> {
    await Promise.all(keys.map((key) => SecureStore.deleteItemAsync(key)));
  },
};

export const CREDENTIAL_KEYS = {
  ACCESS_TOKEN: "fintech_access_token",
  REFRESH_TOKEN: "fintech_refresh_token",
  DEVICE_ID: "fintech_device_id",
  ENCRYPTION_KEY: "fintech_encryption_key",
  BIOMETRIC_ENROLLED: "fintech_biometric_enrolled",
} as const;

For session management, the token in Redux (in-memory) is fine for the session lifetime. But you need active timeout enforcement:

// src/security/session-manager.ts

import { AppState, AppStateStatus } from "react-native";
import { CredentialStore, CREDENTIAL_KEYS } from "./secure-storage";

export interface SessionConfig {
  inactivityTimeoutMs: number; // 5 minutes for banking apps
  backgroundTimeoutMs: number; // 2 minutes in background
  heartbeatIntervalMs: number; // Check every 30 seconds
  onSessionExpired: () => void;
  onTokenRefreshNeeded: () => Promise<boolean>;
}

class SessionManager {
  private lastActivityTimestamp: number = Date.now();
  private backgroundTimestamp: number | null = null;
  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
  private appStateSubscription: any = null;

  start(tokenExpiryMs?: number): void {
    this.lastActivityTimestamp = Date.now();

    // Monitor app state changes (foreground/background)
    this.appStateSubscription = AppState.addEventListener(
      "change",
      this.handleAppStateChange,
    );

    // Periodic heartbeat to check session validity
    this.heartbeatTimer = setInterval(
      () => this.checkSession(),
      this.config.heartbeatIntervalMs,
    );
  }

  recordActivity(): void {
    this.lastActivityTimestamp = Date.now();
  }

  private handleAppStateChange = (nextState: AppStateStatus): void => {
    if (nextState === "background" || nextState === "inactive") {
      this.backgroundTimestamp = Date.now();
    } else if (nextState === "active") {
      if (this.backgroundTimestamp) {
        const backgroundDuration = Date.now() - this.backgroundTimestamp;
        if (backgroundDuration > this.config.backgroundTimeoutMs) {
          this.expireSession("background_timeout");
          return;
        }
      }
      this.checkSession();
    }
  };

  private async expireSession(reason: string): Promise<void> {
    this.stop();
    await CredentialStore.clearAll([
      CREDENTIAL_KEYS.ACCESS_TOKEN,
      CREDENTIAL_KEYS.REFRESH_TOKEN,
    ]);
    this.config.onSessionExpired();
  }
}

Production gotcha: The fintech app I audited stored LAST_ACTIVE_KEY in AsyncStorage for session tracking. That means a sophisticated attacker could modify the timestamp to prevent session expiry. Store session timestamps in memory only — if the app restarts, the session should be treated as expired anyway.

In the Demo App

The Secure Storage screen shows the difference visually. On the left: AsyncStorage storing your token as plaintext JSON. On the right: SecureStore encrypting it with AES-256-GCM in the Secure Enclave. The live demo lets you store, retrieve, and delete a secret — proving the round-trip works and the Keychain entry is fully wiped on delete.

Checklist

[ ] Auth tokens stored in expo-secure-store or react-native-keychain, never AsyncStorage
[ ] Session timeout enforced (5 min inactivity, 2 min background for banking)
[ ] Tokens cleared on logout, session expiry, and excessive failed auth attempts
[ ] No API keys, secrets, or tokens hardcoded in source — use server-side config

M2: Inadequate Supply Chain Security

The RN-specific risk: Your node_modules folder contains hundreds of packages, each maintained by different people with different security practices. A single compromised dependency can exfiltrate user data. This isn't theoretical — event-stream, ua-parser-js, and colors all had real supply chain attacks.

Real-World Incident: In 2021, ParkMobile's breach exposed 21 million users' personal data — names, emails, phone numbers, license plates, and hashed passwords — all because of a vulnerability in a third-party integration. The app itself wasn't directly compromised; a dependency was. In the npm ecosystem, this risk is amplified: your package-lock.json contains hundreds of transitive dependencies you never explicitly chose, each one a potential attack surface.

The event-stream incident (2018) is the textbook example. A user named right9ctrl social-engineered their way into maintainer access of the popular event-stream package (used by 3,931 other packages including @vue/cli-ui, vscode, and nodemon). After a series of innocent commits to build trust, they added a new dependency called flatmap-stream — which contained an encrypted malicious payload hidden in its minified source code. The payload was surgically targeted: it would only decrypt and execute when built as part of Copay, a Bitcoin wallet app, using the app's own npm_package_description as the decryption key. Once active, it harvested Bitcoin wallet private keys and balances above 100 BTC. The attack was downloaded 8 million times and went undetected for over a month — only discovered because of an unrelated OpenSSL deprecation warning in nodemon.

React Native adds extra risk because many packages include native modules (Objective-C, Java/Kotlin) that most JavaScript developers never audit. A native module has full device access — it can read the filesystem, make network calls, and access hardware without any JavaScript-visible API surface.

// package.json — lock your dependencies
{
  "dependencies": {
    "expo-secure-store": "15.0.8",
    "react-native-mmkv": "4.3.1",
    "react-native-ssl-public-key-pinning": "1.2.6"
  }
}

Use exact versions (not ^ or ~) for security-critical packages. Add these to your CI pipeline:

# CI audit command
npm audit --audit-level=high
npx better-npm-audit audit --level high

# Check for known vulnerabilities in native dependencies
npx expo-doctor

# Verify package provenance (npm v9.5+)
npm audit signatures

What to watch for:

Packages with no updates in 12+ months (abandonware)
Packages with a single maintainer and recent ownership transfer
Native modules that request permissions your app doesn't need
Transitive dependencies pulling in unexpected native code

Checklist

[ ] npm audit runs in CI and blocks on high/critical vulnerabilities
[ ] Security-critical packages use exact versions, not ranges
[ ] Review native module permissions before adding new dependencies
[ ] Package-lock.json is committed and reviewed in PRs

M3: Insecure Authentication and Authorization

The real issue in RN fintech: Most apps only require biometric auth at login. But a pen tester will check whether you can access the payment screen, view account balances, or initiate transfers without re-authenticating. If you authenticate once at login and then trust the session for everything, a stolen unlocked device = full access.

Real-World Incident: In 2018, Facebook's photo API bug exposed 6.8 million users' private photos — including photos they had uploaded but never posted. The vulnerability was an insufficient authorization check: third-party apps that were granted permission to view a user's timeline photos could also access their unpublished, Marketplace, and Stories photos. The API simply didn't enforce granular access control on the resource. In a fintech context, this is the equivalent of a payment confirmation endpoint that doesn't re-verify whether the authenticated user is the account owner — one missing authorization check and any authenticated user can access any account.

The fix: biometric gates on sensitive screens, not just login.

// src/security/biometric-auth.ts

import * as LocalAuthentication from "expo-local-authentication";
import { Platform } from "react-native";

export async function authenticateWithBiometrics(options: {
  reason: string;
  allowDeviceFallback?: boolean;
}): Promise<BiometricAuthResult> {
  const capability = await checkBiometricCapability();

  if (!capability.isAvailable || !capability.isEnrolled) {
    return {
      success: false,
      error:
        Platform.OS === "ios"
          ? "Please set up Face ID or Touch ID in Settings."
          : "Please set up fingerprint in Settings.",
      userCancelled: false,
    };
  }

  const result = await LocalAuthentication.authenticateAsync({
    promptMessage: options.reason,
    disableDeviceFallback: !options.allowDeviceFallback,
    fallbackLabel: options.allowDeviceFallback ? "Use Passcode" : "",
  });

  if (result.success) {
    return { success: true, userCancelled: false };
  }

  const userCancelled =
    result.error === "user_cancel" || result.error === "system_cancel";

  return {
    success: false,
    error: getBiometricErrorMessage(result.error),
    userCancelled,
  };
}

The BiometricGateScreen wraps any sensitive screen. The child component doesn't even mount until auth succeeds — preventing any mount-time data fetching:

// src/screens/BiometricGateScreen.tsx

export function BiometricGateScreen({
  children,
  reason = "Authenticate to continue",
  allowFallback = false,
  onAuthFailure,
}: BiometricGateScreenProps) {
  const { capability, isEnrolled, authenticate, isLoading } = useBiometrics();
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const [attempts, setAttempts] = useState(0);
  const MAX_ATTEMPTS = 3;

  useEffect(() => {
    if (!isLoading && capability?.isAvailable && isEnrolled) {
      handleAuthenticate();
    }
  }, [isLoading]);

  const handleAuthenticate = async () => {
    if (attempts >= MAX_ATTEMPTS) {
      onAuthFailure?.();
      return;
    }

    const result = await authenticate(reason, {
      allowDeviceFallback: allowFallback,
    });
    if (result.success) {
      setIsAuthenticated(true);
    } else if (!result.userCancelled) {
      setAttempts((prev) => prev + 1);
    }
  };

  if (isAuthenticated) {
    return <>{children}</>;
  }

  // ... render authentication prompt UI
}

Simulator gotcha: LocalAuthentication.authenticateAsync() always succeeds on iOS Simulator when Face ID is "enrolled" (Features > Face ID > Enrolled). On Android emulators, behavior varies by version. Always test biometric flows on a real device before your security audit. I've seen teams ship with biometric "protection" that they only ever tested on simulators.

Physical spoofing risk: Face ID has been bypassed with 3D-printed masks and fingerprint sensors with lifted prints. For high-value transactions (payments, withdrawals), always combine biometrics with a secondary factor — device passcode fallback at minimum, or a server-validated OTP for transactions above a threshold. Biometrics alone is a convenience feature, not a security guarantee.

In the Demo App

The Biometric Auth screen shows your device's capability (hardware, enrollment, security level, supported types), then lets you trigger two auth flows: a login prompt with passcode fallback, and a strict payment prompt with biometric-only (no fallback). The result box turns green on success, red on failure.

Checklist

[ ] Biometric auth gates on payment, balance view, and settings screens — not just login
[ ] Maximum attempt limit with lockout after failures
[ ] Tested on real devices, not just simulators
[ ] Fallback strategy defined (device passcode for low-risk, no fallback for payments)

M4: Insufficient Input/Output Validation

SQL injection in local SQLite: Yes, it happens in mobile apps. If you build SQLite queries with string concatenation, you're vulnerable.

Real-World Context: Input validation failures aren't just about SQL injection. WhatsApp's buffer overflow vulnerability (CVE-2019-3568) allowed attackers to install spyware with a single VoIP call — the target didn't even need to answer. The root cause was insufficient validation of incoming data in the call signaling protocol. In a React Native fintech context, your deep link handler and payment input fields are the most exposed surfaces — they accept data from outside your trust boundary (other apps, URLs, clipboard) and feed it directly into your business logic.

// ❌ WRONG — SQL injection in local database
const query = `SELECT * FROM transactions WHERE account_id = '${accountId}'`;
db.execAsync(query);

// ✅ RIGHT — Parameterized query
const result = db.getAllAsync(
  "SELECT * FROM transactions WHERE account_id = ?",
  [accountId],
);

Deep link hijacking: React Native apps register URL schemes (yourfintech://) that can be invoked by any app on the device. If you don't validate deep link parameters, an attacker can craft a link that redirects to a phishing page or triggers unintended actions.

// src/security/certificate-check.ts

export function validateDeepLink(url: string): {
  valid: boolean;
  sanitizedUrl?: string;
  reason?: string;
} {
  try {
    const parsed = new URL(url);

    // Only allow your app's registered schemes
    const allowedSchemes = ["yourfintech", "https"];
    if (!allowedSchemes.includes(parsed.protocol.replace(":", ""))) {
      return { valid: false, reason: `Disallowed scheme: ${parsed.protocol}` };
    }

    // For https links, only allow your domains
    if (parsed.protocol === "https:") {
      const allowedHosts = ["yourfintech.com", "app.yourfintech.com"];
      if (!allowedHosts.includes(parsed.hostname)) {
        return { valid: false, reason: `Disallowed host: ${parsed.hostname}` };
      }
    }

    // Reject script injection in parameters
    for (const [key, value] of parsed.searchParams) {
      if (/<script/i.test(value) || /javascript:/i.test(value)) {
        return { valid: false, reason: `Suspicious parameter in ${key}` };
      }
    }

    return { valid: true, sanitizedUrl: parsed.toString() };
  } catch {
    return { valid: false, reason: "Malformed URL" };
  }
}

Amount validation for payments — this is fintech-specific and gets missed:

// src/screens/SecurePaymentScreen.tsx

const validateAmount = (value: string): string | null => {
  const num = parseFloat(value);
  if (isNaN(num)) return "Please enter a valid amount.";
  if (num <= 0) return "Amount must be positive.";
  if (num > 50000) return "Amount exceeds single transaction limit.";
  // Precision attack prevention (e.g., 0.001 to drain funds via rounding)
  if (value.includes(".") && value.split(".")[1].length > 2) {
    return "Amount cannot have more than 2 decimal places.";
  }
  return null;
};

In the Demo App

The Deep Link Validation screen has a live URL input — type or paste any URL and it validates in real time. The input border turns green for allowed URLs and red for blocked ones. Tap any of the preset buttons (phishing domain, XSS payload, JS injection, wrong scheme) to see them rejected instantly with a reason.

Checklist

[ ] All SQLite queries use parameterized statements, never string concatenation
[ ] Deep links validated against an allowlist of schemes and hosts
[ ] Payment amounts validated for range, precision, and format
[ ] TextInput fields use textContentType="none" and autoComplete="off" for sensitive data

M5: Insecure Communication

SSL pinning is mandatory for fintech. Without it, anyone on the same WiFi with a proxy (Charles, mitmproxy) and a self-signed CA installed on the device can read all your API traffic — including auth tokens, account numbers, and transaction data.

Real-World Incident: The British Airways breach in 2018 is the definitive example of what happens without communication security. Attackers injected a malicious script (just 22 lines of JavaScript) into the BA website and mobile app that skimmed payment card data — names, card numbers, CVVs, and expiry dates — as customers typed them. The data was exfiltrated to a look-alike domain (baways.com) in real time. 500,000 customers were affected and BA was fined £20 million by the ICO. The attack worked because there was no integrity check on the scripts being loaded and no pinning to verify the communication channel. In a React Native app without SSL pinning, an attacker on the same WiFi running mitmproxy achieves the same result — intercepting every API call, including payment data, in plaintext.

Hash pinning vs. certificate pinning: Use hash pinning. When you pin a certificate, you pin the entire cert — including its expiry date. When it rotates (every 90 days with Let's Encrypt), your pins break. Hash pinning pins the public key's SPKI hash, which survives cert renewals if the same key pair is reused.

How to extract your pin hash:

openssl s_client -connect api.yourfintech.com:443 \
  -servername api.yourfintech.com < /dev/null 2>/dev/null \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary \
  | base64

// src/security/ssl-pinning.ts

import {
  initializeSslPinning,
  isSslPinningAvailable,
} from "react-native-ssl-public-key-pinning";

// Initialize once at app startup — after this, all fetch() calls
// are automatically pinned for the configured domains.
const PINNING_CONFIG = {
  "api.yourfintech.com": {
    includeSubdomains: true,
    publicKeyHashes: [
      // Primary: current certificate's public key hash
      "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      // Backup: pre-generated backup key pair (CRITICAL — iOS requires 2+)
      "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
      // Disaster recovery: CA intermediate key hash
      "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",
    ],
    // Safety valve: after this date, pinning degrades to normal TLS
    expirationDate: "2026-12-31",
  },
};

// Call this in your app's entry point
if (isSslPinningAvailable()) {
  initializeSslPinning(PINNING_CONFIG);
}
// After initialization, standard fetch() is automatically pinned.

The #1 production gotcha — cert rotation: If you only pin one hash and your certificate rotates with a new key pair, every user is locked out until they update through the App Store. This is not a hypothetical — I've seen it happen. Mitigations:

Always pin at least 2 hashes (current + backup key pair)

Set expirationDate — after this date, pinning disables gracefully

Monitor cert expiry server-side and push updated pins via OTA (expo-updates)

Have a kill switch — a remote config flag to disable pinning in emergencies

The secure API client wraps all of this into a clean interface:

// src/api/secureClient.ts

export function createSecureClient(config: SecureClientConfig) {
  // After initializeSslPinning(), the standard fetch() is automatically pinned.
  // No special fetch import needed — just use global fetch.

  async function request<T>(
    method: string,
    path: string,
    options?: RequestOptions,
  ) {
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
    };

    // Inject auth token from SecureStore (not Redux, not AsyncStorage)
    if (!options?.skipAuth) {
      const token = await CredentialStore.getToken(
        CREDENTIAL_KEYS.ACCESS_TOKEN,
      );
      if (token) headers["Authorization"] = `Bearer ${token}`;
    }

    // Anti-replay: nonce + timestamp
    const nonce = await generateSecureHex(16);
    headers["X-Request-Nonce"] = nonce;
    headers["X-Request-Timestamp"] = Date.now().toString();

    // Request signing for tamper detection
    if (config.requestSigningKey) {
      const payload = `${method}:${path}:${headers["X-Request-Timestamp"]}:${nonce}`;
      headers["X-Request-Signature"] = await hmacSha256(
        payload,
        config.requestSigningKey,
      );
    }

    try {
      const response = await fetch(url, { method, headers, body });
      return response;
    } catch (error) {
      if (error instanceof SSLPinningError) {
        // Potential MITM — log to security monitoring
        throw createApiError("Secure connection failed.", { code: "SSL_PIN" });
      }
      throw error;
    }
  }
}

In the Demo App

The SSL Pinning screen makes real HTTPS requests to demonstrate the concept. First, a normal fetch to jsonplaceholder.typicode.com succeeds — proving the network works. Then, the same request with a deliberately wrong pin hash gets BLOCKED before any data is sent. An ASCII diagram shows how a proxy attack works with and without pinning.

Checklist

[ ] SSL public key pinning enabled for all API endpoints
[ ] Minimum 2 pin hashes configured (current + backup)
[ ] expirationDate set as a safety valve
[ ] Cert rotation plan documented and tested
[ ] Pin validation tested on a real device through a proxy (should fail)

M6: Inadequate Privacy Controls

What data you're accidentally logging: Flipper (the React Native debugger) logs every network request by default — including auth headers, request bodies with PII, and response bodies with account data. Sentry and Crashlytics capture breadcrumbs that often include screen names ("PaymentScreen"), user actions ("entered amount: 5000"), and even full stack traces with variable values.

Real-World Incident: In 2018, the MyFitnessPal breach exposed 150 million accounts — Under Armour disclosed that usernames, email addresses, and hashed passwords were stolen. Forensic analysis revealed that sensitive data was accessible in plaintext in the app's cache directory at /data/data/com.myfitnesspal/cache/ — extractable with one adb shell command on a rooted device. The data wasn't just in the database — it was in log files and cached API responses that nobody thought to encrypt. Your Sentry breadcrumbs and Flipper network logs are the React Native equivalent: unencrypted records of everything your user does, stored on disk.

// src/api/secureClient.ts

const SENSITIVE_FIELDS = [
  "token",
  "accessToken",
  "refreshToken",
  "password",
  "pin",
  "ssn",
  "accountNumber",
  "routingNumber",
  "cardNumber",
  "cvv",
];

export function maskSensitiveData(
  data: Record<string, any>,
): Record<string, any> {
  const masked = { ...data };
  for (const key of Object.keys(masked)) {
    if (
      SENSITIVE_FIELDS.some((f) => key.toLowerCase().includes(f.toLowerCase()))
    ) {
      const value = masked[key];
      masked[key] =
        typeof value === "string" && value.length > 4
          ? `***${value.slice(-4)}`
          : "***";
    } else if (typeof masked[key] === "object" && masked[key] !== null) {
      masked[key] = maskSensitiveData(masked[key]);
    }
  }
  return masked;
}

export function secureLog(label: string, data?: any): void {
  if (!__DEV__) return; // No logging in production
  if (data && typeof data === "object") {
    console.log(`[SECURE] ${label}`, maskSensitiveData(data));
  }
}

Screenshot & screen recording prevention (iOS + Android): expo-screen-capture handles both platforms with a single API. On Android, it sets FLAG_SECURE (blocks screenshots, recordings, AND blanks the app switcher preview). On iOS 13+, it uses the UITextField.isSecureTextEntry trick to block screenshots and recordings, plus a separate blur overlay for the app switcher.

npx expo install expo-screen-capture

// src/security/screenshot-prevention.ts

import * as ScreenCapture from "expo-screen-capture";
import { Platform } from "react-native";
import { useEffect, useRef } from "react";

/**
 * Prevents screenshots + recordings while the component is mounted.
 * Cleanup is automatic on unmount — other screens aren't affected.
 */
export function usePreventScreenCapture(key: string = "default"): void {
  useEffect(() => {
    ScreenCapture.preventScreenCaptureAsync(key);
    return () => {
      ScreenCapture.allowScreenCaptureAsync(key);
    };
  }, [key]);
}

/**
 * Maximum protection: blocks capture + blurs app switcher preview.
 * Use on payment, card details, OTP, and PIN screens.
 */
export function useSecureScreen(key: string = "default"): void {
  useEffect(() => {
    ScreenCapture.preventScreenCaptureAsync(key);
    if (Platform.OS === "ios") {
      ScreenCapture.enableAppSwitcherProtectionAsync(0.8);
    }
    return () => {
      ScreenCapture.allowScreenCaptureAsync(key);
      if (Platform.OS === "ios") {
        ScreenCapture.disableAppSwitcherProtectionAsync();
      }
    };
  }, [key]);
}

/**
 * Detect screenshot attempts for monitoring/logging.
 * Does NOT prevent — use alongside usePreventScreenCapture.
 */
export function useScreenshotDetection(onScreenshot: () => void): void {
  const callbackRef = useRef(onScreenshot);
  callbackRef.current = onScreenshot;

  useEffect(() => {
    const sub = ScreenCapture.addScreenshotListener(() =>
      callbackRef.current(),
    );
    return () => sub.remove();
  }, []);
}

Use it on any sensitive screen — one line:

// src/screens/SecurePaymentScreen.tsx

function PaymentForm() {
  // Blocks screenshots, recordings, and app switcher preview (iOS + Android)
  useSecureScreen("payment-screen");

  // Log screenshot attempts to your SIEM
  useScreenshotDetection(() => {
    secureLog("Screenshot attempt on PaymentScreen");
    Alert.alert(
      "Screenshot Detected",
      "For your security, please avoid capturing screenshots of payment information.",
    );
  });

  // ... rest of the screen
}

Platform coverage matrix:

Threat Android iOS

Screenshots FLAG_SECURE isSecureTextEntry trick (iOS 13+)

Screen recordings FLAG_SECURE Same mechanism

App switcher preview FLAG_SECURE (automatic) enableAppSwitcherProtectionAsync() (blur)

AirPlay / screen mirror N/A Blocked by capture prevention

Why per-screen, not app-wide: Blocking screenshots globally is hostile UX. Users should be able to screenshot their transaction history or support chat. Only block on screens showing card details, CVV, balances, payment confirmation, OTP entry, and PIN entry.

Threat	Android	iOS
Screenshots	`FLAG_SECURE`	`isSecureTextEntry` trick (iOS 13+)
Screen recordings	`FLAG_SECURE`	Same mechanism
App switcher preview	`FLAG_SECURE` (automatic)	`enableAppSwitcherProtectionAsync()` (blur)
AirPlay / screen mirror	N/A	Blocked by capture prevention

In the Demo App

Screenshot Prevention: Toggle protection on/off and take screenshots to see the difference. With protection disabled, your screenshot captures the full card number, CVV, and balance. Enable it, screenshot again — the capture is black. The detection counter increments each time. Background the app to see the app switcher blur.

04-screenshot-demo.mp4 - Google Drive

drive.google.com

PII Masking: The demo shows raw sensitive data (red block) next to the masked output (green block), field by field. Tokens, passwords, SSNs, and card numbers are replaced with *** plus last 4 characters. Non-sensitive fields like userName and email pass through unchanged.

Sentry/Crashlytics configuration for fintech:

// Don't send PII in crash reports
Sentry.init({
  beforeSend(event) {
    // Strip user data
    if (event.user) {
      delete event.user.email;
      delete event.user.ip_address;
    }
    // Strip sensitive breadcrumb data
    event.breadcrumbs = event.breadcrumbs?.map((b) => ({
      ...b,
      data: b.data ? maskSensitiveData(b.data) : undefined,
    }));
    return event;
  },
  beforeBreadcrumb(breadcrumb) {
    // Don't log network request bodies
    if (breadcrumb.category === "fetch" || breadcrumb.category === "xhr") {
      delete breadcrumb.data?.body;
      delete breadcrumb.data?.response_body;
    }
    return breadcrumb;
  },
});

Checklist

[ ] PII masking applied to all log outputs (console, Sentry, Crashlytics)
[ ] Network request/response bodies stripped from crash reports
[ ] useSecureScreen() on payment, card, OTP, and PIN screens (iOS + Android)
[ ] App switcher blur enabled on iOS via enableAppSwitcherProtectionAsync()
[ ] Screenshot detection logging to SIEM on sensitive screens
[ ] Flipper and Reactotron disabled in production builds

M7: Insufficient Binary Protections

React Native's specific weakness: Your entire business logic ships as a JavaScript bundle (index.android.bundle / main.jsbundle). Without protections, anyone can extract and read it.

Real-World Incident: In 2022, the Lapsus$ group breached Samsung and leaked 190GB of source code — including device authentication logic, DRM modules, and Knox security platform source code. The leaked code was extracted, decompiled, and analyzed by attackers worldwide. Samsung confirmed the breach affected "source code relating to the operation of Galaxy devices" but stated no customer data was compromised. The damage, however, was done: proprietary security logic was now public, making targeted attacks on Samsung devices significantly easier. React Native apps face an even lower bar — your JavaScript bundle is essentially readable source code that can be extracted from any APK with unzip and a text editor, no sophisticated decompilation required.

Hermes bytecode compilation is the first line of defense. Hermes compiles JavaScript to bytecode at build time, making casual reverse engineering harder (not impossible, but significantly harder than reading plain JavaScript):

// app.json
{
  "expo": {
    "jsEngine": "hermes"
  }
}

ProGuard/R8 for Android obfuscates the native Java/Kotlin layer:

// android/app/build.gradle
def enableProguardInReleaseBuilds = true

android {
    buildTypes {
        release {
            minifyEnabled enableProguardInReleaseBuilds
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                         'proguard-rules.pro'
        }
    }
}

Strip source maps in production: Source maps map bytecode back to your original TypeScript. Never include them in your production bundle:

// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");

const config = getDefaultConfig(__dirname);

if (process.env.NODE_ENV === "production") {
  config.transformer = {
    ...config.transformer,
    minifierConfig: {
      compress: {
        drop_console: true, // Remove console.log statements
      },
    },
  };
}

module.exports = config;

Disable debug mode in production: Verify that __DEV__ is false in production builds. Metro automatically sets this, but verify it:

if (__DEV__) {
  // This entire block is stripped from production bundles by Metro
  console.log("Debug mode active");
}

Checklist

[ ] Hermes engine enabled (bytecode compilation)
[ ] ProGuard/R8 enabled for Android release builds
[ ] Source maps uploaded to crash reporting service but NOT bundled in the app
[ ] console.log statements stripped in production (drop_console: true)
[ ] Debug mode verified as disabled in release builds

M8: Security Misconfiguration

Jailbreak/root detection without false-positives. Here's the problem: if you just check isJailBroken() and block the app, your Android developers with unlocked bootloaders can't test the app. So they add if (__DEV__) return false and forget to remove it. Or worse, they disable the check entirely.

The solution: a proper developer bypass that's architecturally impossible to trigger in production.

// src/security/jailbreak-detection.ts

import * as SecureStore from "expo-secure-store";

// jail-monkey provides native jailbreak/root detection
let JailMonkey: any = null;
try {
  JailMonkey = require("jail-monkey");
} catch {
  // Expected in Expo Go — works in production builds
}

export async function checkDeviceSecurity(): Promise<DeviceSecurityStatus> {
  const status: DeviceSecurityStatus = {
    isCompromised: false,
    isJailbroken: false,
    isRooted: false,
    isDebugged: false,
    reasons: [],
    devBypassed: false,
  };

  // Developer bypass — ONLY in __DEV__ builds (stripped by Metro in production)
  if (__DEV__ && (await isDevBypassEnabled())) {
    status.devBypassed = true;
    return status;
  }

  if (!JailMonkey) {
    if (!__DEV__) {
      status.isCompromised = true;
      status.reasons.push("Security module unavailable");
    }
    return status;
  }

  if (JailMonkey.isJailBroken()) {
    status.isCompromised = true;
    status.reasons.push(
      Platform.OS === "ios"
        ? "Device appears to be jailbroken"
        : "Device appears to be rooted",
    );
  }

  if ((await JailMonkey.isDebuggedMode()) && !__DEV__) {
    status.isCompromised = true;
    status.reasons.push("Debugger detected");
  }

  return status;
}

The developer bypass system: The bypass token is stored in SecureStore and only checked when __DEV__ is true. Since __DEV__ is a compile-time constant that Metro sets to false in production builds, the entire bypass code path is dead-code-eliminated. Even if an attacker extracts and sets the bypass token, it has no effect in a production binary.

// src/security/jailbreak-detection.ts

const DEV_BYPASS_KEY = "fintech_dev_jailbreak_bypass";

export async function enableDevBypass(): Promise<void> {
  if (!__DEV__) {
    throw new Error("Dev bypass cannot be enabled in production");
  }
  await SecureStore.setItemAsync(DEV_BYPASS_KEY, "DEV_SECURITY_BYPASS_ACTIVE");
}

// Call from your dev menu:
// enableDevBypass().then(() => console.log('Bypass enabled'));

Response strategy — don't just block: Different contexts warrant different responses:

export function getCompromisedAction(
  status: DeviceSecurityStatus,
  context: "payment" | "sensitive_data" | "app_launch" | "general",
): "block" | "warn" | "limit" | "allow" {
  if (status.devBypassed) return "allow";
  if (!status.isCompromised) return "allow";

  switch (context) {
    case "payment":
      return "block"; // Never allow payments on compromised devices
    case "sensitive_data":
      return "block"; // Block financial data viewing
    case "app_launch":
      return "warn"; // Warn but let user see non-sensitive features
    default:
      return "warn";
  }
}

OTA update security: If you use expo-updates, verify that updates are signed and come from your server. A compromised OTA update can inject malicious code without going through App Store review.

In the Demo App

Tap "Scan Device" and watch each check run: native module loaded, jailbreak/root status, debugger detection, __DEV__ guard, and the resulting payment action (ALLOWED or BLOCKED). On a clean simulator you'll see all green. On a jailbroken device, the jailbreak row turns red and payments are blocked.

Checklist

[ ] Jailbreak/root detection active in production builds
[ ] Developer bypass uses __DEV__ guard (dead-code-eliminated in production)
[ ] Graduated response: block payments, warn on general use
[ ] OTA updates configured with code signing verification

M9: Insecure Data Storage

The AsyncStorage trap. I cannot stress this enough: AsyncStorage is not encrypted. It stores data as plaintext JSON files. On Android, it's in the app's shared preferences directory. On iOS, it's in the app's documents directory. A rooted device, an unencrypted backup, or a forensic extraction tool can read everything.

Here's a tiered storage strategy:

Tier 1 — Credentials (Keychain/Keystore): Use expo-secure-store for tokens, API keys, PII, and encryption keys. Backed by hardware encryption on devices with Secure Enclave (iOS) or StrongBox (Android).

Tier 2 — App data (encrypted MMKV): Use react-native-mmkv with an encryption key stored in Tier 1. 30x faster than AsyncStorage, and encrypted at rest.

// src/security/secure-storage.ts

import { MMKV } from "react-native-mmkv";
import * as SecureStore from "expo-secure-store";
import * as Crypto from "expo-crypto";

async function getOrCreateEncryptionKey(): Promise<string> {
  let key = await SecureStore.getItemAsync("fintech_encryption_key");

  if (!key) {
    // Generate 256-bit key with CSPRNG
    const randomBytes = await Crypto.getRandomBytesAsync(32);
    key = Array.from(new Uint8Array(randomBytes))
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");
    await SecureStore.setItemAsync("fintech_encryption_key", key, {
      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    });
  }
  return key;
}

export async function getEncryptedStorage(): Promise<MMKV> {
  const encryptionKey = await getOrCreateEncryptionKey();
  return new MMKV({
    id: "fintech-encrypted-storage",
    encryptionKey,
  });
}

Tier 3 — Structured data (encrypted SQLite): For transaction history, contacts, etc., use expo-sqlite with column-level encryption. Encrypt sensitive fields before writing:

import { sha256 } from "./crypto-utils";

// Encrypt sensitive columns before storage
const encryptedName = await encryptForStorage(accountName, encryptionKey);
db.runAsync(
  "INSERT INTO accounts (id, name_encrypted, type) VALUES (?, ?, ?)",
  [accountId, encryptedName, accountType],
);

What stays in AsyncStorage: Theme preference. Language selection. Whether the user has seen the onboarding carousel. That's it.

Checklist

[ ] Tokens and PII in expo-secure-store (Keychain/Keystore)
[ ] App data in encrypted MMKV with Keychain-stored encryption key
[ ] Sensitive SQLite columns encrypted before storage
[ ] AsyncStorage used ONLY for non-sensitive preferences
[ ] redux-persist storage backend changed from AsyncStorage to SecureStore for auth state

M10: Insufficient Cryptography

Math.random() is not cryptographically secure. It uses a PRNG (Pseudo-Random Number Generator) seeded from system time. If you use it for transaction IDs, OTP generation, or anything security-sensitive, an attacker can predict the sequence.

Real-World Incident: In 2019, security researchers discovered that Twitter had been storing passwords in plaintext in internal logs — affecting all 330 million users. The passwords were written to logs before the hashing function was applied, meaning anyone with access to the log system could read them. Twitter urged all users to change their passwords. The root cause: the hashing step was in the wrong place in the pipeline. In the same vein, Adobe's 2013 breach initially reported 2.9 million credit card records stolen, but later analysis revealed 153 million user accounts were affected. The passwords were encrypted with 3DES in ECB mode — which preserves patterns, meaning identical passwords produced identical ciphertext — instead of properly hashed with bcrypt or Argon2. Security researchers could cross-reference the password hints with the repeated ciphertext blocks to crack millions of passwords without even breaking the encryption. Weak cryptography isn't just using the wrong algorithm; it's using the right algorithm in the wrong way. Math.random() for transaction IDs, SHA-1 for password hashing, or AES with a hardcoded key are all variations of the same mistake: cryptography that looks secure but isn't.

// ❌ WRONG — Predictable "random" IDs
const transactionId = Math.random().toString(36).substring(2);
const otp = Math.floor(Math.random() * 1000000)
  .toString()
  .padStart(6, "0");

// ✅ RIGHT — Cryptographically secure random
import * as Crypto from "expo-crypto";

export async function generateSecureHex(
  byteCount: number = 16,
): Promise<string> {
  const bytes = await Crypto.getRandomBytesAsync(byteCount);
  return Array.from(new Uint8Array(bytes))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

export async function generateSecureId(length: number = 32): Promise<string> {
  const bytes = await Crypto.getRandomBytesAsync(length);
  const charset =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
  return Array.from(new Uint8Array(bytes))
    .map((b) => charset[b % charset.length])
    .join("");
}

Key derivation — PBKDF2, not bare hashing:

// ❌ WRONG — No stretching, vulnerable to brute force
const key = await sha256(userPin); // 4-digit PIN = 10,000 attempts

// ✅ RIGHT — Iterated key derivation with salt
export async function deriveKey(
  input: string,
  salt: string,
  iterations: number = 10000,
): Promise<string> {
  let derived = `${salt}:${input}`;
  for (let i = 0; i < iterations; i++) {
    derived = await Crypto.digestStringAsync(
      Crypto.CryptoDigestAlgorithm.SHA256,
      derived,
    );
  }
  return derived;
}

Production note: The iterated SHA-256 approach above is a PBKDF2 approximation for environments where native PBKDF2 isn't available. For production, use react-native-quick-crypto which provides proper PBKDF2 with configurable iterations. OWASP 2024 recommends 600,000 iterations for PBKDF2-SHA256. In a pure expo-crypto environment, 10,000 iterations of SHA-256 is a reasonable floor.

In the Demo App

The Crypto Utils screen puts Math.random() and CSPRNG side by side. Tap "Generate 5 Random Values" — the left column (red) shows predictable PRNG output, the right column (green) shows hardware-backed random bytes. Below that, type any text and hash it with SHA-256 in real time. The key derivation demo shows the intentional delay — tap "Derive Key from PIN 1234" and watch it take 100+ milliseconds for 1000 iterations.

Checklist

[ ] Math.random() never used for security-sensitive values
[ ] All random generation uses expo-crypto CSPRNG
[ ] Key derivation uses iterated hashing with salt (PBKDF2 or equivalent)
[ ] No MD5 or SHA1 usage anywhere in the codebase
[ ] Encryption keys generated with CSPRNG and stored in Keychain/Keystore

The Full Checklist

Print this. Tape it to your monitor. Check every item before submitting for security review.

#	Control	Action
M1	Credential Storage	Tokens in Keychain/Keystore via `expo-secure-store`, not AsyncStorage
M1	Session Timeout	5-min inactivity + 2-min background timeout enforced
M2	Supply Chain	`npm audit` in CI, exact versions for security packages
M2	Dependency Review	Native module permissions reviewed before adding packages
M3	Biometric Auth	Gates on all sensitive screens, not just login
M3	Auth Fallback	Max attempt limits, tested on real devices
M4	SQL Injection	Parameterized queries for all SQLite operations
M4	Deep Links	Validated against scheme/host allowlist
M4	Input Validation	Amount range, precision, and format checks for payments
M5	SSL Pinning	Public key hash pinning with 2+ pins (current + backup)
M5	Cert Rotation	`expirationDate` safety valve + rotation plan documented
M6	PII in Logs	Sensitive fields masked in all log outputs
M6	Crash Reports	Request/response bodies stripped from Sentry/Crashlytics
M6	Screenshots	`useSecureScreen()` via expo-screen-capture on iOS + Android
M7	Hermes	Bytecode compilation enabled
M7	ProGuard	R8/ProGuard enabled for Android release builds
M7	Source Maps	Stripped from production bundle, uploaded to crash service only
M7	Debug Mode	`console.log` stripped, `__DEV__` verified false in release
M8	Jailbreak	Detection active with developer bypass via `__DEV__` guard
M8	Response Strategy	Graduated: block payments, warn on general use
M8	OTA Security	Code signing verification for expo-updates
M9	Tier 1 Storage	Credentials in Keychain/Keystore
M9	Tier 2 Storage	App data in encrypted MMKV
M9	Tier 3 Storage	SQLite with column-level encryption
M9	AsyncStorage	Used ONLY for non-sensitive preferences
M10	CSPRNG	`expo-crypto` for all random generation
M10	Key Derivation	Iterated SHA-256 with salt (or PBKDF2 via quick-crypto)
M10	No Weak Crypto	No MD5, no SHA1, no `Math.random()` for security

What a Security Audit Actually Looks For

I've worked with pen testing teams on RN apps. Here's what they check first — in order:

1. Network traffic interception. They install a proxy (Burp Suite, mitmproxy) on a rooted device with a custom CA certificate. If they can see plaintext API traffic, that's a critical finding. SSL pinning stops this — it's the first thing they test.

2. Local data extraction. They pull the app's data directory from a rooted device and search for tokens, PII, and financial data in plaintext. AsyncStorage is the first place they look. Shared preferences is second. If your tokens are in either, that's another critical.

3. Binary analysis. They extract the APK/IPA, unzip it, and examine the JavaScript bundle. They search for hardcoded API keys, endpoint URLs, secret keys, and validation logic. Hermes bytecode makes this harder but not impossible — tools like hermes-dec can decompile Hermes bytecode back to readable JavaScript.

4. Runtime manipulation. On a jailbroken device, they use Frida or Objection to hook into your app at runtime. They can bypass biometric checks, modify function return values, and intercept encrypted data before it's encrypted. Jailbreak detection catches this scenario — or at least makes it harder and shows your auditors you're trying.

5. Debug artifacts and extraneous functionality. They look for hidden API endpoints, debug parameters (?isAdmin=true — see the Peloton incident above), console logging in production, and leftover test screens. They'll also check if Flipper, Reactotron, or the React Native dev menu is accessible in your release build.

Tools they'll use against your app:

Tool	What It Does	What It Finds
MobSF	Static + dynamic analysis	Exported components, hardcoded keys, insecure storage
Frida	Runtime hooking	Bypass biometrics, modify function returns, intercept decrypted data
Objection	Runtime exploration (built on Frida)	Dump Keychain, bypass SSL pinning, explore the filesystem
Burp Suite	HTTP proxy + scanner	API vulnerabilities, missing pinning, auth bypass
Jadx / hermes-dec	Decompiler	Hardcoded secrets, business logic, API endpoints in your bundle
Drozer	Android IPC testing	Exposed Intents, Content Providers, Broadcast Receivers

Beyond build-time protection — RASP: Consider deploying Runtime Application Self-Protection (RASP) for your highest-security flows. Unlike jailbreak detection which checks once at launch, RASP monitors continuously for code injection, function hooking (Frida), debugger attachment, and memory tampering. Tools like Talsec freeRASP provide a React Native SDK. This doesn't replace the controls in this article — it adds a real-time detection layer on top of them.

The common thread: pen testers assume a rooted/jailbroken device. They assume the attacker has physical access. They assume the network is hostile. Your security controls need to hold up under all three assumptions simultaneously.

Conclusion

Security in React Native fintech isn't one big thing — it's 30 small things done right. No single control is sufficient. SSL pinning without secure storage is pointless (the attacker reads the token from disk). Secure storage without session timeout is pointless (a stolen token works forever). Biometric auth without jailbreak detection is pointless (Frida bypasses it in 5 minutes).

The code in this article is real, tested, and production-ready. Every file exists in the companion repo with full implementations. Clone it, adapt it to your domain, and use the checklist above as your pre-audit scorecard.

If you're about to go through a security audit for your RN fintech app, start with M1 (credential storage) and M5 (SSL pinning). Those two controls address the most common critical findings. Then work through the rest of the list. Your pen testers will thank you — or at least, they'll have to work harder to find something.

Companion repo: github.com/FastheDeveloper/owasp-rn-fintech

Built with expo-secure-store@15.x, expo-crypto@15.x, expo-local-authentication@17.x, react-native-ssl-public-key-pinning@1.2.x, react-native-mmkv@4.x, and jail-monkey@3.x.

WatermelonDB + Expo SDK 54: The Complete Mobile Offline-First Setup Guide That Actually Works 🍉

Farouq Seriki — Mon, 11 May 2026 13:37:53 +0000

From MMKV queues to reactive SQLite — what I learned engineering a production offline-first architecture that handles any scenario

⚡ TL;DR

The MMKV + TanStack Query pattern is a perfectly valid offline strategy — until you need relational queries, conflict resolution, or reactive UI updates on local data

WatermelonDB on Expo SDK 54 (new arch mandatory, React 19) requires the community Expo plugin, peer dependency overrides, and specific native patches — the official docs alone will not get you there

PowerSync and ElectricSQL + TanStack DB are serious alternatives with different tradeoff profiles — this guide compares all three from a full-stack perspective

Every config file (app.plugin.js, eas.json, Podfile patches) is included with exact version numbers — no "left as an exercise for the reader"

Full working demo repo: github.com/FastheDeveloper/watermelondb-expo-offline-demo

🛠️ Prerequisites

Before diving in, make sure you have:

Node.js 20+ (LTS)
Expo CLI (npx expo — no global install needed)
EAS CLI (npm install -g eas-cli) for building native binaries
Xcode 16+ (for iOS simulator builds on Apple Silicon)
Android Studio with NDK installed (for Android builds)
A working Expo SDK 54 project — or willingness to create one
Familiarity with TanStack Query — this guide builds on top of it, not from scratch

Version matrix used in this article:

Package	Version
Expo SDK	54
React Native	0.81.5
React	19.1.0
TypeScript	5.9.x
@nozbe/watermelondb	0.28.0
@tanstack/react-query	5.100.x
react-native-mmkv	4.3.x
@powersync/react-native	1.34.0

📌 Bookmark this table. You will come back to it when a peer dep error makes you question your life choices.

🧵 The Pattern That Got Me Here

I want to be upfront about where I started.

A couple of years ago, I was building a field operations app — think workers in rural areas confirming tasks, uploading images, syncing data when they got back to signal. The offline requirement was clear: if you are offline, your work should not be lost.

Here is what I shipped:

// offlineStorage.ts — the MMKV queue pattern
import { MMKV } from "react-native-mmkv";

const storage = new MMKV();
const OFFLINE_QUEUE_KEY = "offline_pending_mutations";

interface OfflineTask<T = Record<string, unknown>> {
  id: number;
  data: T;
  timestamp: number;
}

export const queueOfflineMutation = <T extends Record<string, unknown>>(
  task: OfflineTask<T>,
): void => {
  const stored = storage.getString(OFFLINE_QUEUE_KEY);
  const queue: OfflineTask<T>[] = stored ? JSON.parse(stored) : [];
  queue.push(task);
  storage.set(OFFLINE_QUEUE_KEY, JSON.stringify(queue));
};

export const getOfflineQueue = <
  T = Record<string, unknown>,
>(): OfflineTask<T>[] => {
  const stored = storage.getString(OFFLINE_QUEUE_KEY);
  return stored ? JSON.parse(stored) : [];
};

export const clearOfflineQueue = (): void => {
  storage.delete(OFFLINE_QUEUE_KEY);
};

Paired with a TanStack Query persister that caches API responses in MMKV:

// queryClient.ts — MMKV-backed TanStack Query persistence
import { QueryClient } from "@tanstack/react-query";
import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
import { MMKV } from "react-native-mmkv";

const mmkv = new MMKV();

const clientStorage = {
  getItem: (key: string): string | null => mmkv.getString(key) ?? null,
  setItem: (key: string, value: string): void => mmkv.set(key, value),
  removeItem: (key: string): void => mmkv.delete(key),
};

export const persister = createSyncStoragePersister({
  storage: clientStorage,
  key: "TANSTACK_QUERY_OFFLINE_CACHE",
});

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24h cache retention
      staleTime: 1000 * 60 * 5, // 5min freshness window
      retry: 2,
      refetchOnWindowFocus: false,
      refetchOnReconnect: true,
      networkMode: "offlineFirst", // serve cache first, then revalidate
    },
    mutations: {
      retry: 1,
      networkMode: "offlineFirst",
    },
  },
});

And a sync hook that drains the queue when connectivity returns:

// useSyncOfflineQueue.ts
import { useEffect } from "react";
import { useNetInfo } from "./useNetInfo";
import { getOfflineQueue, clearOfflineQueue } from "../utils/offlineStorage";

export const useSyncOfflineQueue = (
  authToken: string | null,
  syncFn: (tasks: OfflineTask[]) => Promise<void>,
  onSuccess?: () => void,
): void => {
  const { isOnline } = useNetInfo();

  useEffect(() => {
    const sync = async (): Promise<void> => {
      if (!isOnline || !authToken) return;

      const queue = getOfflineQueue();
      if (queue.length === 0) return;

      try {
        await syncFn(queue);
        clearOfflineQueue();
        onSuccess?.();
      } catch (error) {
        // Queue stays intact — retry on next connectivity change
        console.error("Offline sync failed, will retry:", error);
      }
    };

    sync();
  }, [isOnline, authToken]);
};

This worked. It shipped. It ran in production for tens of thousands of users. Workers could go offline, confirm tasks, attach photos, and everything synced when signal returned.

So why write about WatermelonDB?

💡 Takeaway: The MMKV queue pattern is a legitimate offline strategy. If your app just needs to cache reads and queue writes, stop reading and use this. Seriously.

🧱 Where the Queue Pattern Hits Its Ceiling

The queue pattern did not fail me. I outgrew it by thinking about harder problems.

When I started designing for more demanding scenarios — apps where users might be offline for hours, needing to browse historical data, filter records, handle multi-step workflows where step 3 depends on data from step 1 — the cracks in the architecture became visible before I even hit them:

1. 🔍 No relational queries offline.
MMKV stores flat JSON blobs. Want "all tasks for Zone A with species Oak planted after March"? You deserialize every record into memory and filter in JavaScript. With 100 records, nobody notices. With 10,000, your users notice.

2. 💣 All-or-nothing sync.
The queue drains in one API call. If one task in a batch of 20 fails validation, nothing syncs. There is no per-record retry, no partial success tracking, no way to surface "18 synced, 2 need attention."

3. 👻 Zero conflict detection.
If a task gets reassigned server-side while a worker is offline, the sync blindly pushes stale data. No version check, no lastPulledAt timestamp, no conflict resolution strategy. The server's truth and the client's truth diverge silently.

4. 🖥️ No reactive UI.
When offline data changes, nothing re-renders. You manually call refetchQueries() after sync. The UI and the data layer are completely decoupled — fine for a cache, terrible for a database.

5. 🎲 No schema enforcement at the storage layer.
MMKV does not care what shape your data is. A typo in a field name is a runtime error you discover in production, not a compile-time error you catch in your editor.

Here is the mental model that clarified things for me:

Cache → Queue → Database → Sync Engine
  ↑        ↑         ↑           ↑
  │        │         │           │
TanStack   MMKV    WatermelonDB  PowerSync /
Query +    queue    (SQLite +    ElectricSQL
persist             observables)

Most developers stop at "Queue" and call it offline-first. Real offline-first starts at "Database."

💡 Takeaway: Once you need to query your offline data — not just store and forward it — you need a database. And once you need a database that syncs, you need a sync strategy.

⚔️ The Landscape: WatermelonDB vs PowerSync vs ElectricSQL

Before the WatermelonDB setup, you deserve to see the full picture. These are the three solutions evaluated seriously, from a full-stack perspective with a mobile focus.

🍉 WatermelonDB — Full Control, Full Responsibility

WatermelonDB is a client-side reactive database built on SQLite, designed specifically for React Native apps with large datasets.

How it works: You define schemas and model classes. WatermelonDB creates SQLite tables, gives you observable queries (UI re-renders when data changes), and provides a sync protocol specification. You build the sync server yourself — pull endpoint, push endpoint, conflict handling, all of it.

The good:

⚡ Fastest client-side queries via JSI (C++ bridge, no serialization overhead)
🔄 Observable/reactive — observe() on a query, UI updates automatically
💤 Lazy loading by default — only loads records when accessed
🆓 MIT licensed. Zero recurring cost. No vendor lock-in.
🏭 Proven at scale — Nozbe uses it in their own production apps

The reality (especially in 2026):

⚠️ @nozbe/with-observables peer deps do not include React 19 — you need overrides
⚠️ Untested on React Native's new architecture (now mandatory in Expo SDK 54)
⚠️ Community Expo plugin has not been updated for SDK 54
⚠️ Last stable release (0.28.0) was April 2025 — over a year ago
🏗️ You build the entire sync backend. Every endpoint, every conflict handler, every retry.

Best for: Teams with backend engineers who want full control over data residency, sync logic, and zero vendor dependency. If you are building fintech or healthcare where you cannot send data through a third-party sync service, this is your option.

⚡ PowerSync — Sync as a Service

PowerSync is an end-to-end sync engine that sits between your backend database and your clients.

How it works: PowerSync connects to your Postgres (or MongoDB/MySQL) via change data capture — logical replication on Postgres, change streams on MongoDB. It streams filtered subsets of data to clients, where it lands in SQLite. Reads sync automatically. Writes go through your own backend API.

The good:

🚫 No client-side schema migrations needed (schemaless SQLite views)
🎯 First-class Expo support with a dedicated config plugin (@powersync/react-native v1.34.0)
🦀 Rust-based sync client enabled by default — fast and reliable
🌍 Multi-platform: React Native, Flutter, Kotlin, Swift, web
🔧 Actively maintained — releases in May 2026

The tradeoffs:

💰 $49/month minimum for production use (free tier deactivates after 1 week of inactivity)
📜 Source-available license, not truly open source
🏗️ You still build write endpoints — it is not a complete backend replacement

Best for: Teams on Postgres/MongoDB who want sync solved, not built. If you would rather configure than code, start here.

🌿 ElectricSQL + TanStack DB — The Open-Source Middle Ground

ElectricSQL is a read-path sync engine from Postgres to clients. TanStack DB layers client-side persistence, live queries, and optimistic mutations on top.

The good:

🆓 Apache 2.0 licensed — genuinely open source
💸 Generous pricing: ~5M writes/month free, then $1/million
🤝 Deep TanStack ecosystem integration
🚀 Active development — @electric-sql/client v1.5.16 released May 2026

The tradeoffs:

🆕 TanStack DB on React Native is newer — less battle-tested than WatermelonDB's years of production use
🔀 Two libraries to coordinate (Electric + TanStack DB) vs one

Best for: Teams already in the TanStack ecosystem who want an open-source path.

📊 The Comparison Table

	WatermelonDB	PowerSync	ElectricSQL + TanStack DB
Client DB	SQLite (JSI)	SQLite	SQLite (expo-sqlite)
Server component	You build it	Managed service	Electric Cloud + your API
Sync direction	Push/pull (you implement)	Auto reads, writes via API	Auto reads, writes via API
Conflict resolution	Reject-on-conflict	Server-side LWW (customizable)	Your backend's responsibility
Expo SDK 54 ready	Needs patches + overrides	✅ Yes (first-class)	✅ Yes
React 19 support	Peer dep issues	✅ Yes	✅ Yes
New Architecture	Untested officially	✅ Supported	✅ Supported
License	MIT	Source-available	Apache 2.0
Price	Free	From $49/mo	~Free under 5M writes/mo
You build	Everything	Write endpoints only	Write endpoints only

🏅 Honorable Mentions

Jazz.tools — CRDT-based local-first framework with first-class Expo support. Ships with auth, permissions, real-time collaboration, and E2E encryption out of the box. If your app needs multiplayer/collaboration features, evaluate this before building from scratch on WatermelonDB.

Legend State — State management with built-in persistence and sync. Think Zustand + offline persistence + sync plugin in one. Good for simpler offline needs without a separate database layer.

RxDB — Reactive NoSQL database with pluggable storage and replication. More flexible backend compatibility than WatermelonDB, but less optimized for React Native specifically.

Realm — MongoDB's on-device database. ⛔ Atlas Device Sync was deprecated in September 2024. Do not start new projects on it for sync.

💡 Takeaway: WatermelonDB gives you the most control but the most work. PowerSync gives you the least work but the most cost. ElectricSQL + TanStack DB is the open-source middle ground. Pick based on your team's backend capacity, budget, and how much you want to own vs rent.

🤔 Why I Chose WatermelonDB (and When I Would Choose Differently)

For the production app where I needed this, the decision came down to four factors:

🔒 Data residency requirements. Fintech. Could not route read sync through a third-party service. WatermelonDB's client-only architecture with a self-built sync server kept all data in our infrastructure.
👥 Existing backend team. We had a NestJS + PostgreSQL backend with engineers who could implement sync endpoints. Building pull/push was not a burden — it was Tuesday.
📊 Offline query volume. Field workers needed to browse, filter, and search through thousands of records with no signal. SQLite with indexed columns was non-negotiable.
💰 Zero recurring cost. MIT license. No per-seat, per-sync, per-month charges. When you are deploying to thousands of devices, this matters.

Here is the honest version though: if I were starting a new project today with a Postgres backend and a small team (2-3 devs), I would evaluate PowerSync first. The $49/month is nothing compared to the engineering hours you burn building and maintaining a sync server. If I needed open source and was already using TanStack Query, I would go ElectricSQL + TanStack DB.

I chose WatermelonDB because I needed full control — and I was willing to fight the setup.

Let me show you that fight. 🥊

🎉 Hey — you are still here. That means you are serious about offline-first and not just looking for a five-minute fix. That puts you ahead of most developers who copy-paste a TanStack Query persister and call it a day. The next section is the one that does not exist anywhere else on the internet. Let's go.

🔧 The Setup That Actually Works: WatermelonDB + Expo SDK 54

This is the section that does not exist anywhere else. Not in the WatermelonDB docs (which target vanilla React Native). Not in the Expo docs (which do not mention WatermelonDB). Not in any single blog post, tutorial, or Stack Overflow answer.

This is every file, every patch, every workaround — verified on Expo SDK 54 with new architecture (mandatory) and React 19.

📦 Installation — The Exact Commands

Start with a fresh Expo SDK 54 project or an existing one:

# Create a new project (if starting fresh)
npx create-expo-app@latest my-offline-app --template default
cd my-offline-app

Install WatermelonDB and its peer dependencies:

# Core WatermelonDB
npx expo install @nozbe/watermelondb

# Observable integration for React
npm install @nozbe/with-observables

# Community Expo config plugin (required for native module linking)
npm install @morrowdigital/watermelondb-expo-plugin@2.4.0-beta.0

🤔 Why @morrowdigital and not @lovesworking? The @morrowdigital plugin has a beta release (2.4.0-beta.0) tested against SDK 54. The @lovesworking fork targets SDK 52/53 specifically. For SDK 54, @morrowdigital is the starting point — and exact patches are covered below. Neither plugin has an official SDK 54 release at time of writing, so expect to troubleshoot. That is exactly why this guide exists.

🩹 Fixing the React 19 Peer Dependency

@nozbe/with-observables@1.6.0 declares react@^16||^17||^18 as a peer dependency. React 19 is not in that range. Two options:

Option A: package.json overrides (recommended ✅)

{
  "overrides": {
    "@nozbe/with-observables": {
      "react": "$react"
    }
  }
}

For Yarn users, use resolutions instead of overrides.

Option B: --legacy-peer-deps

npm install --legacy-peer-deps

This works but silences all peer dependency warnings, which can mask real issues. Option A is surgical precision.

🔌 The Expo Config Plugin

Add the WatermelonDB plugin to your app.json (or app.config.ts):

{
  "expo": {
    "plugins": [
      [
        "@morrowdigital/watermelondb-expo-plugin",
        {
          "disableJsi": false
        }
      ]
    ]
  }
}

⚡ disableJsi: false enables the JSI (JavaScript Interface) adapter — the C++ bridge that makes WatermelonDB queries up to 3x faster than the bridge-based adapter. With new architecture being mandatory in SDK 54, JSI is the expected path. If you hit JSI-related crashes during development, set this to true temporarily to isolate the issue.

If the plugin does not work out of the box with SDK 54, you may need a custom config plugin. Here is a minimal one:

// plugins/withWatermelonDB.ts
import { ConfigPlugin, withDangerousMod } from "expo/config-plugins";
import * as fs from "fs";
import * as path from "path";

const withWatermelonDBAndroid: ConfigPlugin = (config) => {
  return withDangerousMod(config, [
    "android",
    async (cfg) => {
      const buildGradlePath = path.join(
        cfg.modRequest.platformProjectRoot,
        "app",
        "build.gradle",
      );

      let buildGradle = fs.readFileSync(buildGradlePath, "utf-8");

      if (!buildGradle.includes("watermelondb-jsi")) {
        const jsiDep = `
    // WatermelonDB JSI
    implementation project(':watermelondb-jsi')`;

        buildGradle = buildGradle.replace(
          /dependencies\s*\{/,
          `dependencies {${jsiDep}`,
        );

        fs.writeFileSync(buildGradlePath, buildGradle);
      }

      return cfg;
    },
  ]);
};

export default withWatermelonDBAndroid;

Then reference it in your config:

{
  "expo": {
    "plugins": ["./plugins/withWatermelonDB"]
  }
}

🗂️ Schema Definition

WatermelonDB schemas are defined in code, not migration files. This is your source of truth:

// src/database/schema.ts
import { appSchema, tableSchema } from "@nozbe/watermelondb";

// Schema version — increment when you add/modify tables or columns
const SCHEMA_VERSION = 1;

export const schema = appSchema({
  version: SCHEMA_VERSION,
  tables: [
    tableSchema({
      name: "tasks",
      columns: [
        { name: "server_id", type: "number", isIndexed: true },
        { name: "title", type: "string" },
        { name: "description", type: "string" },
        { name: "status", type: "string", isIndexed: true },
        { name: "task_type", type: "string" },
        { name: "due_date", type: "number" }, // stored as timestamp
        { name: "location_name", type: "string" },
        { name: "latitude", type: "number", isOptional: true },
        { name: "longitude", type: "number", isOptional: true },
        { name: "is_synced", type: "boolean" }, // local sync tracking
        { name: "last_modified", type: "number" }, // server timestamp
        { name: "created_at", type: "number" },
        { name: "updated_at", type: "number" },
      ],
    }),
    tableSchema({
      name: "task_confirmations",
      columns: [
        { name: "task_id", type: "string", isIndexed: true },
        { name: "tree_species_id", type: "number" },
        { name: "trees_planted_count", type: "number" },
        { name: "remarks", type: "string", isOptional: true },
        { name: "latitude", type: "number", isOptional: true },
        { name: "longitude", type: "number", isOptional: true },
        { name: "is_synced", type: "boolean" },
        { name: "created_at", type: "number" },
        { name: "updated_at", type: "number" },
      ],
    }),
    tableSchema({
      name: "confirmation_images",
      columns: [
        { name: "confirmation_id", type: "string", isIndexed: true },
        { name: "local_uri", type: "string" },
        { name: "remote_url", type: "string", isOptional: true },
        { name: "is_uploaded", type: "boolean" },
        { name: "created_at", type: "number" },
        { name: "updated_at", type: "number" },
      ],
    }),
  ],
});

Key decisions worth noting:

server_id vs WatermelonDB's internal id: WatermelonDB generates its own UUIDs for all records. Your server's integer IDs go in server_id. This dual-ID pattern is essential for sync — you need to map between local and remote records.
is_synced flag: WatermelonDB's sync protocol uses its own tracking, but an explicit flag gives you query-level visibility (showing a "pending sync" badge in the UI, for example).
Timestamps as numbers: WatermelonDB stores dates as Unix timestamps in milliseconds. Do not fight this — convert at the boundary.
isIndexed on foreign keys and filter columns: SQLite indexes make a real difference on 10k+ record tables. Index anything you filter or join on.

🏗️ Model Classes

Models are where WatermelonDB gets opinionated. With new architecture and TypeScript 5.9, we avoid legacy decorators and use the field descriptor API:

// src/database/models/Task.ts
import { Model } from "@nozbe/watermelondb";
import {
  field,
  text,
  date,
  readonly,
  children,
  writer,
} from "@nozbe/watermelondb/decorators";
import type { Associations } from "@nozbe/watermelondb/Model";

export default class Task extends Model {
  static table = "tasks";

  static associations: Associations = {
    task_confirmations: { type: "has_many" as const, foreignKey: "task_id" },
  };

  @field("server_id") serverId!: number;
  @text("title") title!: string;
  @text("description") description!: string;
  @text("status") status!: string;
  @text("task_type") taskType!: string;
  @date("due_date") dueDate!: Date;
  @text("location_name") locationName!: string;
  @field("latitude") latitude!: number | null;
  @field("longitude") longitude!: number | null;
  @field("is_synced") isSynced!: boolean;
  @field("last_modified") lastModified!: number;
  @readonly @date("created_at") createdAt!: Date;
  @readonly @date("updated_at") updatedAt!: Date;

  @children("task_confirmations") confirmations!: any;

  @writer async markAsSynced(): Promise<void> {
    await this.update((record) => {
      record.isSynced = true;
    });
  }

  @writer async updateStatus(newStatus: string): Promise<void> {
    await this.update((record) => {
      record.status = newStatus;
      record.isSynced = false; // Mark for re-sync
    });
  }
}

// src/database/models/TaskConfirmation.ts
import { Model } from "@nozbe/watermelondb";
import {
  field,
  text,
  date,
  readonly,
  relation,
  children,
  writer,
} from "@nozbe/watermelondb/decorators";
import type { Associations } from "@nozbe/watermelondb/Model";

export default class TaskConfirmation extends Model {
  static table = "task_confirmations";

  static associations: Associations = {
    tasks: { type: "belongs_to" as const, key: "task_id" },
    confirmation_images: {
      type: "has_many" as const,
      foreignKey: "confirmation_id",
    },
  };

  @relation("tasks", "task_id") task!: any;
  @field("tree_species_id") treeSpeciesId!: number;
  @field("trees_planted_count") treesPlantedCount!: number;
  @text("remarks") remarks!: string | null;
  @field("latitude") latitude!: number | null;
  @field("longitude") longitude!: number | null;
  @field("is_synced") isSynced!: boolean;
  @readonly @date("created_at") createdAt!: Date;
  @readonly @date("updated_at") updatedAt!: Date;

  @children("confirmation_images") images!: any;

  @writer async markAsSynced(): Promise<void> {
    await this.update((record) => {
      record.isSynced = true;
    });
  }
}

// src/database/models/ConfirmationImage.ts
import { Model } from "@nozbe/watermelondb";
import {
  field,
  text,
  date,
  readonly,
  relation,
  writer,
} from "@nozbe/watermelondb/decorators";
import type { Associations } from "@nozbe/watermelondb/Model";

export default class ConfirmationImage extends Model {
  static table = "confirmation_images";

  static associations: Associations = {
    task_confirmations: { type: "belongs_to" as const, key: "confirmation_id" },
  };

  @relation("task_confirmations", "confirmation_id") confirmation!: any;
  @text("local_uri") localUri!: string;
  @text("remote_url") remoteUrl!: string | null;
  @field("is_uploaded") isUploaded!: boolean;
  @readonly @date("created_at") createdAt!: Date;
  @readonly @date("updated_at") updatedAt!: Date;

  @writer async markAsUploaded(url: string): Promise<void> {
    await this.update((record) => {
      record.remoteUrl = url;
      record.isUploaded = true;
    });
  }
}

🔍 Why decorators still work: WatermelonDB uses TypeScript experimental decorators (stage 2), not the TC39 standard decorators (stage 3). TypeScript 5.9 supports both — you need "experimentalDecorators": true in your tsconfig.json. This is a known rough edge the WatermelonDB team has not resolved yet.

🚀 Database Initialization

// src/database/index.ts
import "./polyfills"; // MUST be first import — see below
import { Database } from "@nozbe/watermelondb";
import SQLiteAdapter from "@nozbe/watermelondb/adapters/sqlite";

import { schema } from "./schema";
import migrations from "./migrations";
import Task from "./models/Task";
import TaskConfirmation from "./models/TaskConfirmation";
import ConfirmationImage from "./models/ConfirmationImage";

const adapter = new SQLiteAdapter({
  schema,
  migrations,
  jsi: true,
  onSetUpError: (error) => {
    // Database setup failed — this is fatal
    // In production you might want to:
    // 1. Report to your crash analytics
    // 2. Attempt to delete and recreate the database
    // 3. Show a "please reinstall" screen as last resort
    console.error("WatermelonDB setup failed:", error);
  },
});

export const database = new Database({
  adapter,
  modelClasses: [Task, TaskConfirmation, ConfirmationImage],
});

🐛 The `window.performance.now.bind` Crash

If you hit this error on app startup:

TypeError: window.performance.now.bind is not a function

This is a known issue where WatermelonDB's internal performance tracking assumes a browser-like window.performance API. The fix is a polyfill that must run before the database is imported:

// src/database/polyfills.ts
// Must be imported before any WatermelonDB import
if (typeof window !== "undefined" && window.performance) {
  const originalNow = window.performance.now;
  if (
    typeof originalNow === "function" &&
    typeof originalNow.bind !== "function"
  ) {
    const now = (): number => originalNow.call(window.performance);
    window.performance.now = now as typeof window.performance.now;
  }
}

export {}; // ensure this is treated as a module

The import './polyfills' at the top of src/database/index.ts handles the ordering automatically.

📋 Schema Migrations

When you add columns or tables in a future version:

// src/database/migrations.ts
import {
  schemaMigrations,
  addColumns,
} from "@nozbe/watermelondb/Schema/migrations";

export default schemaMigrations({
  migrations: [
    // Example: adding a priority column in version 2
    // {
    //   toVersion: 2,
    //   steps: [
    //     addColumns({
    //       table: 'tasks',
    //       columns: [
    //         { name: 'priority', type: 'string', isOptional: true },
    //       ],
    //     }),
    //   ],
    // },
  ],
});

📌 Production tip: Always keep your migrations file even if it is empty. When you need to add a column six months from now and your app is on 50k devices, you will be glad the infrastructure is already in place. Always test migrations on a device running the old schema before shipping — simulators with fresh installs do not catch migration bugs.

⚙️ EAS Build Configuration

// eas.json
{
  "cli": {
    "version": ">= 15.0.0",
    "appVersionSource": "remote"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "buildConfiguration": "Debug",
        "simulator": true
      },
      "android": {
        "buildType": "apk"
      },
      "env": {
        "EXPO_NO_TELEMETRY": "1"
      }
    },
    "preview": {
      "distribution": "internal",
      "ios": {
        "simulator": false
      },
      "android": {
        "buildType": "apk"
      }
    },
    "production": {
      "autoIncrement": true,
      "ios": {
        "buildConfiguration": "Release"
      },
      "android": {
        "buildType": "app-bundle"
      }
    }
  }
}

⚠️ Important: WatermelonDB is a native module. You cannot use Expo Go. You must use a development build (npx expo run:ios or eas build --profile development). OTA updates via EAS Update work for JavaScript changes, but any WatermelonDB version bump or schema change requires a new native build.

🍎 iOS-Specific: The `simdjson` Duplicate Dependency

This one will catch you. After npx expo prebuild, running pod install fails with:

[!] There are multiple dependencies with different sources for `simdjson` in `Podfile`

What is happening: The WatermelonDB Expo config plugin inserts a manual pod 'simdjson' line into your Podfile. But Expo's autolinking also discovers @nozbe/simdjson in node_modules and tries to link it. Two sources, one pod, CocoaPods rejects it.

Fix: Open ios/Podfile and delete the manual simdjson line the plugin added:

# DELETE this entire line — autolinking already handles it
pod 'simdjson', path: File.join(File.dirname(`node --print "require.resolve('@nozbe/simdjson/package.json')"`)), :modular_headers => true

Then re-run:

cd ios && pod install && cd ..

Apple Silicon Simulator Build Failure 🖥️

If you hit a build failure on M1/M2/M3 related to simdjson architecture, add this to your Podfile's post_install block:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'i386'
    end
  end
end

🔷 TypeScript Configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "strict": true,
    "experimentalDecorators": true,
    "jsx": "react-jsx"
  }
}

experimentalDecorators is required for WatermelonDB's model decorators. Non-negotiable until WatermelonDB migrates to standard decorators.

✅ Takeaway: If you followed these steps exactly with the versions listed, you have a working WatermelonDB setup on Expo SDK 54. If something broke, the Troubleshooting section at the end catalogs every error you are likely to hit.

🙌 Checkpoint — seriously, well done. You just got through the hardest part of this entire guide. The setup section alone is what hundreds of developers have been hunting for across GitHub issues, Discord threads, and unanswered Stack Overflow posts. You now have a working native database on Expo SDK 54 with new arch enabled. What is left is the fun part — making it actually sync.

🔄 Sync Implementation — The Full-Stack View

This is where WatermelonDB's "you own the sync" philosophy becomes real work. The protocol is well-specified but you build every piece.

🧠 The Sync Protocol (Mental Model)

WatermelonDB's sync is a two-phase operation:

Client                          Server
  │                               │
  ├─── PULL ─────────────────────►│  "Give me everything changed since timestamp X"
  │◄── {created, updated, deleted}│  Server responds with change sets per table
  │                               │
  ├─── PUSH ─────────────────────►│  "Here's everything I changed locally"
  │    {created, updated, deleted}│  Server validates and applies
  │◄── OK or REJECT ─────────────│  If conflict detected → reject entire push
  │                               │
  ├─── (if rejected) PULL again──►│  Re-pull, merge, retry push
  │                               │

Critical detail: The pull must return a consistent snapshot. On the server, wrap your pull query in a transaction with a serializable isolation level. If records change mid-pull, the client will have an inconsistent view and the next push will likely fail.

🖥️ Expo API Routes — The Demo Backend

For the demo project, I used Expo Router API routes — server-side endpoints that live inside the same repo as the mobile app. No separate backend project, no extra process to run. npx expo start serves both the mobile app and the sync API.

The sync server state lives in an in-memory store (swap out for Postgres in production):

// src/services/serverStore.ts
import type { RawTaskRecord, RawConfirmationRecord } from "../types";

export let serverTasks: RawTaskRecord[] = generateSeedTasks();
export let serverConfirmations: RawConfirmationRecord[] = [];

export function applyTaskUpdate(
  updated: Partial<RawTaskRecord> & { id: string },
): void {
  const idx = serverTasks.findIndex((t) => t.id === updated.id);
  if (idx !== -1) {
    serverTasks[idx] = {
      ...serverTasks[idx],
      ...updated,
      last_modified: Date.now(),
    };
  }
}

export function addConfirmation(record: RawConfirmationRecord): void {
  serverConfirmations.push({ ...record, is_synced: true });
}

Pull endpoint — returns all changes since the client's last sync:

// app/api/sync/pull+api.ts
import {
  serverTasks,
  serverConfirmations,
} from "../../../src/services/serverStore";

export function GET(request: Request): Response {
  const url = new URL(request.url);
  const lastPulledAt = Number(url.searchParams.get("last_pulled_at") ?? "0");
  const isFirstPull = lastPulledAt === 0;

  if (isFirstPull) {
    return Response.json({
      changes: {
        tasks: { created: serverTasks, updated: [], deleted: [] },
        task_confirmations: {
          created: serverConfirmations,
          updated: [],
          deleted: [],
        },
      },
      timestamp: Date.now(),
    });
  }

  const modifiedTasks = serverTasks.filter(
    (t) => t.last_modified > lastPulledAt,
  );
  const newTasks = modifiedTasks.filter((t) => t.created_at > lastPulledAt);
  const updatedTasks = modifiedTasks.filter(
    (t) => t.created_at <= lastPulledAt,
  );

  return Response.json({
    changes: {
      tasks: { created: newTasks, updated: updatedTasks, deleted: [] },
      task_confirmations: { created: [], updated: [], deleted: [] },
    },
    timestamp: Date.now(),
  });
}

Push endpoint — receives client changes and applies them server-side:

// app/api/sync/push+api.ts
import {
  applyTaskUpdate,
  addConfirmation,
} from "../../../src/services/serverStore";

export async function POST(request: Request): Promise<Response> {
  const { changes } = await request.json();

  if (changes.tasks) {
    for (const updated of changes.tasks.updated) {
      applyTaskUpdate(updated);
    }
  }

  if (changes.task_confirmations) {
    for (const created of changes.task_confirmations.created) {
      addConfirmation(created);
    }
  }

  return Response.json({ ok: true });
}

📌 Why this works for a demo but not production: The in-memory store resets when the dev server restarts. There is no auth, no conflict detection, no transactions. But the shape of the API is identical to what WatermelonDB expects — so swapping in a real database is replacing the store functions with SQL queries.

🪝 Client Sync Hook

// src/hooks/useSync.ts
import { synchronize } from "@nozbe/watermelondb/sync";
import { database } from "../database";
import { API_BASE_URL } from "../constants/config";

const performSync = async (): Promise<void> => {
  await synchronize({
    database,

    pullChanges: async ({ lastPulledAt }) => {
      const response = await fetch(
        `${API_BASE_URL}/api/sync/pull?last_pulled_at=${lastPulledAt ?? 0}`,
      );

      if (!response.ok) {
        throw new Error(`Pull failed: ${response.status}`);
      }

      return response.json();
    },

    pushChanges: async ({ changes, lastPulledAt }) => {
      const response = await fetch(`${API_BASE_URL}/api/sync/push`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ changes, last_pulled_at: lastPulledAt }),
      });

      if (!response.ok) {
        throw new Error(`Push failed: ${response.status}`);
      }
    },

    migrationsEnabledAtVersion: 1,
  });
};

Key design decisions:

An isSyncing ref guard (in the full hook) prevents concurrent sync calls. WatermelonDB's synchronize is not re-entrant — two concurrent calls will corrupt state.
Pull sends lastPulledAt — WatermelonDB manages this timestamp automatically. The first sync sends 0, which tells the server "give me everything."
Push errors do not clear local changes. If push fails, your local mutations stay in WatermelonDB's internal change tracking and will be included in the next push attempt automatically.

🌐 Auto-Sync on Reconnect

// src/providers/SyncProvider.tsx
import React, { createContext, useEffect, type PropsWithChildren } from "react";
import { AppState } from "react-native";
import { useSync } from "../hooks/useSync";
import { useNetInfo } from "../hooks/useNetInfo";

export const SyncProvider = ({ children }: PropsWithChildren) => {
  const { sync, isSyncing, lastSyncedAt, lastError } = useSync();
  const { isOnline } = useNetInfo();

  // Sync when connectivity is restored
  useEffect(() => {
    if (isOnline) sync();
  }, [isOnline]);

  // Sync when app returns to foreground
  useEffect(() => {
    const sub = AppState.addEventListener("change", (state) => {
      if (state === "active") sync();
    });
    return () => sub.remove();
  }, [sync]);

  // Initial sync on mount
  useEffect(() => {
    sync();
  }, []);

  return (
    <SyncContext.Provider
      value={{ isSyncing, lastSyncedAt, lastError, triggerSync: sync }}
    >
      {children}
    </SyncContext.Provider>
  );
};

🏭 Production Backend: NestJS + PostgreSQL

When you move beyond the demo, replace the in-memory store with a real database. The sync contract stays identical — the client does not change, only the server implementation.

// sync.controller.ts (NestJS)
import {
  Controller,
  Get,
  Post,
  Query,
  Body,
  UseGuards,
  Req,
} from "@nestjs/common";
import { AuthGuard } from "../auth/auth.guard";
import { SyncService } from "./sync.service";

@Controller("sync")
@UseGuards(AuthGuard)
export class SyncController {
  constructor(private readonly syncService: SyncService) {}

  @Get("pull")
  async pull(
    @Req() req: { user: { id: number } },
    @Query("last_pulled_at") lastPulledAt: string,
  ) {
    return this.syncService.pull(req.user.id, parseInt(lastPulledAt, 10) || 0);
  }

  @Post("push")
  async push(
    @Req() req: { user: { id: number } },
    @Body() body: { changes: Record<string, any>; last_pulled_at: number },
  ) {
    return this.syncService.push(
      req.user.id,
      body.changes,
      body.last_pulled_at,
    );
  }
}

// sync.service.ts (NestJS)
import { Injectable, ConflictException } from "@nestjs/common";
import { DataSource } from "typeorm";

@Injectable()
export class SyncService {
  constructor(private readonly dataSource: DataSource) {}

  async pull(userId: number, lastPulledAt: number) {
    // SERIALIZABLE transaction — prevents phantom reads during pull
    return this.dataSource.transaction("SERIALIZABLE", async (manager) => {
      const since = new Date(lastPulledAt);

      const allTasks = await manager.query(
        `SELECT * FROM tasks WHERE user_id = $1 AND last_modified_at > $2`,
        [userId, since],
      );

      const created = allTasks.filter(
        (t: any) => t.created_at > since && !t.deleted_at,
      );
      const updated = allTasks.filter(
        (t: any) =>
          t.created_at <= since && !t.deleted_at && t.last_modified_at > since,
      );
      const deleted = allTasks
        .filter((t: any) => t.deleted_at && t.deleted_at > since)
        .map((t: any) => t.watermelon_id);

      return {
        changes: {
          tasks: {
            created: created.map(this.toWatermelonRecord),
            updated: updated.map(this.toWatermelonRecord),
            deleted,
          },
        },
        timestamp: Date.now(),
      };
    });
  }

  async push(
    userId: number,
    changes: Record<string, any>,
    lastPulledAt: number,
  ) {
    return this.dataSource.transaction("SERIALIZABLE", async (manager) => {
      for (const [tableName, tableChanges] of Object.entries(changes)) {
        for (const record of (tableChanges as any).updated || []) {
          const serverRecord = await manager.query(
            `SELECT last_modified_at FROM ${tableName} WHERE watermelon_id = $1`,
            [record.id],
          );

          if (
            serverRecord.length > 0 &&
            new Date(serverRecord[0].last_modified_at).getTime() > lastPulledAt
          ) {
            throw new ConflictException(
              `Conflict: ${tableName}/${record.id} modified after client's last pull`,
            );
          }

          await manager.query(
            `UPDATE ${tableName} SET title = $2, status = $3, updated_at = NOW() WHERE watermelon_id = $1`,
            [record.id, record.title, record.status],
          );
        }

        for (const record of (tableChanges as any).created || []) {
          await manager.query(
            `INSERT INTO ${tableName} (watermelon_id, title, status, created_at, updated_at)
             VALUES ($1, $2, $3, NOW(), NOW())
             ON CONFLICT (watermelon_id) DO NOTHING`,
            [record.id, record.title, record.status],
          );
        }

        for (const id of (tableChanges as any).deleted || []) {
          await manager.query(
            `UPDATE ${tableName} SET deleted_at = NOW() WHERE watermelon_id = $1`,
            [id],
          );
        }
      }
    });
  }

  private toWatermelonRecord(dbRecord: any) {
    return {
      id: dbRecord.watermelon_id,
      server_id: dbRecord.id,
      title: dbRecord.title,
      description: dbRecord.description,
      status: dbRecord.status,
      task_type: dbRecord.task_type,
      due_date: new Date(dbRecord.due_date).getTime(),
      location_name: dbRecord.location_name,
      latitude: dbRecord.latitude,
      longitude: dbRecord.longitude,
      is_synced: true,
      last_modified: new Date(dbRecord.last_modified_at).getTime(),
      created_at: new Date(dbRecord.created_at).getTime(),
      updated_at: new Date(dbRecord.updated_at).getTime(),
    };
  }
}

Key backend requirements for production:

🔒 SERIALIZABLE transaction isolation — prevents phantom reads during pull. Without this, a record could be modified between your SELECT and the response.
🔑 watermelon_id column — every synced table stores the WatermelonDB-generated UUID alongside your server's auto-increment id. This is the join key between client and server.
🗑️ Soft deletes — WatermelonDB's sync protocol requires deleted records to be returned in the pull response. Hard deletes break sync. Use a deleted_at column.
⚠️ Conflict means reject entire push — the client re-pulls the latest state, WatermelonDB merges internally, and retries. Simpler than field-level merge, but conflicts cause an extra round trip.

🔁 The migration path from demo to production: Your mobile code does not change at all. Point EXPO_PUBLIC_API_URL at your Node.js server instead of localhost:8081. The sync contract is identical — only the backing store changes from in-memory arrays to Postgres tables.

⚡ Conflict Resolution in Practice

WatermelonDB's "reject on conflict" strategy is simple but has UX implications.

// ❌ Don't silently retry forever
const syncWithRetry = async (): Promise<void> => {
  while (true) {
    try {
      await sync();
      return;
    } catch {
      await new Promise((r) => setTimeout(r, 1000));
    }
  }
};

// ✅ Bounded retry with backoff and user feedback
const MAX_SYNC_RETRIES = 3;

const syncWithRetry = async (): Promise<{
  success: boolean;
  retries: number;
}> => {
  let retries = 0;

  while (retries < MAX_SYNC_RETRIES) {
    try {
      await sync();
      return { success: true, retries };
    } catch (error) {
      retries++;

      if (retries >= MAX_SYNC_RETRIES) {
        return { success: false, retries };
      }

      // Exponential backoff: 1s, 2s, 4s
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, retries - 1)));
    }
  }

  return { success: false, retries };
};

💡 Takeaway: The sync is the hard part. WatermelonDB gives you a protocol, not a solution. You build the server, handle conflicts, manage retries, and decide what the user sees when things do not line up.

🔥 You are in the home stretch. Everything from here is hardening, troubleshooting, and decision-making guidance. The core architecture is done. Take a breath — you have just built something most React Native tutorials never even attempt to explain properly.

🛡️ Production Hardening

Schema Migrations Between App Versions

When you add a column after launch:

Increment version in schema.ts
Add a migration step in migrations.ts
🧪 Test on a device running the old version first — do not just test on a fresh install

export default schemaMigrations({
  migrations: [
    {
      toVersion: 2,
      steps: [
        addColumns({
          table: "tasks",
          columns: [{ name: "priority", type: "string", isOptional: true }],
        }),
      ],
    },
  ],
});

☢️ Database Reset Strategy

Sometimes migrations fail (corrupted local DB, dramatic schema changes between versions). Have a fallback:

const adapter = new SQLiteAdapter({
  schema,
  migrations,
  jsi: true,
  onSetUpError: (error) => {
    // Nuclear option: delete and recreate
    // Only do this if you can re-sync all data from the server
    database.unsafeResetDatabase();
  },
});

⚠️ Warning: unsafeResetDatabase() deletes all local data. Only use this if your server is the source of truth and the client can re-pull everything. For apps where users create data offline that has not synced yet, this means data loss. Show a confirmation dialog first.

⚡ Performance Tips

Batch writes: Use database.write(async (writer) => { ... }) to group multiple record operations into a single transaction. Creating 100 records one at a time = 100 SQLite transactions. Batching = 1 transaction.
Index your filter columns: If you query tasks by status frequently, make sure status has isIndexed: true in the schema.
Use @lazy for expensive relations: @lazy defers loading until the property is accessed, preventing N+1 query patterns.
Limit observed queries: Every observe() subscription is a live SQLite query. Do not observe tables you are not rendering.

🐞 Troubleshooting — The Errors You Will Actually Hit

💬 Each of these cost me real hours. Consider this section a gift.

❌ `window.performance.now.bind is not a function`

When: App startup, before any database operations.
Cause: WatermelonDB's internal performance measurement assumes browser-like performance.now with a .bind method. Hermes does not provide this.
Fix: The polyfill in the Database Initialization section above. Must be imported before any WatermelonDB import.

❌ `simdjson` duplicate dependency in Podfile

When: Running pod install after npx expo prebuild.

Error:

[!] There are multiple dependencies with different sources for `simdjson` in `Podfile`

Cause: The WatermelonDB Expo config plugin adds a manual pod 'simdjson' line to your Podfile. Expo's autolinking also discovers @nozbe/simdjson in node_modules. Two sources for the same pod = conflict.

Fix: Open ios/Podfile, delete the manual simdjson line the plugin added, then re-run cd ios && pod install.

❌ `simdjson` build failure on Apple Silicon simulators

When: Building for iOS simulator on an M1/M2/M3 Mac.
Cause: simdjson does not build for the i386 architecture, which the simulator SDK still references.
Fix: Add 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' = 'i386' to your Podfile's post_install block.

❌ `@nozbe/with-observables` React 19 peer dependency warning

When: npm install or npx expo install.
Cause: Package declares react@^16||^17||^18, does not include 19.
Fix: overrides in package.json — Option A from the Installation section.

❌ JSI not loading on Android

When: Database operations crash or fall back to bridge mode silently.
Cause: The Expo config plugin did not link the JSI native module correctly for the new architecture build.
Fix: Verify that android/app/build.gradle includes the watermelondb-jsi project dependency.

❌ EAS Update OTA push does not include schema changes

When: You shipped a schema version bump via EAS Update (OTA) instead of a native build.
Cause: WatermelonDB schema changes require SQLite DDL operations that only run with a native binary rebuild. OTA updates only ship JavaScript.
Fix: Any schema or migration change requires eas build. Use OTA updates only for JavaScript/UI changes that do not touch the database schema.

🔀 Migration Path: From MMKV Queues to WatermelonDB

If you are currently running the MMKV queue pattern and want to migrate, here is the sequence:

Phase 1 — Read cache migration. Replace TanStack Query's MMKV persister with WatermelonDB for your most-queried data. Keep the MMKV queue for writes. This lets you validate the WatermelonDB setup without touching your write path.

Phase 2 — Write queue migration. Move offline mutations from the MMKV queue to WatermelonDB records with an is_synced: false flag. Your sync hook now queries WatermelonDB for unsynced records instead of reading the MMKV queue.

Phase 3 — Full sync. Implement the pull/push sync protocol. Remove the MMKV queue entirely. TanStack Query can still be used for non-synced data (user profile, app config).

🚦 Run both systems in parallel during transition. Do not rip out MMKV until WatermelonDB sync has been stable in production for at least two release cycles. Feature-flag it if your team supports that.

🥊 Pick Your Fighter: The Decision Tree

Not every app needs the same offline strategy. Here is how to decide:

"I just need to cache API responses"
→ 🟢 TanStack Query + MMKV persister. Done. Do not overcomplicate it.

"I need to queue mutations while offline"
→ 🟢 TanStack Query + MMKV mutation queue. The pattern from the first section. Works for simple, linear write operations.

"I need to query offline data — filter, sort, search across thousands of records"
→ 🟡 You need a local database. Choose between:

WatermelonDB — full control, MIT license, you build the sync server
PowerSync — managed sync, $49/mo+, minimal backend work

"I need real-time sync with Postgres and I want open source"
→ 🟡 ElectricSQL + TanStack DB. Generous free tier, Apache 2.0, but the React Native persistence layer is newer.

"I need real-time collaboration with automatic conflict resolution"
→ 🔵 Jazz.tools (CRDT-based, first-class Expo support) or evaluate CRDTs (Automerge/Yjs) if you need fine-grained control.

🏁 Conclusion

I have shipped all three levels of offline architecture in production: the MMKV cache, the mutation queue, and the full reactive database with sync. Each was the right call at the time. The MMKV pattern is where I started — it is honest, pragmatic, and handles more cases than people give it credit for. But when I needed relational queries on thousands of offline records, conflict-aware sync, and reactive UI that updates when the local database changes, I needed a real offline-first architecture.

WatermelonDB delivered that. Setting it up on Expo SDK 54 with mandatory new architecture was genuinely painful — community plugins, peer dependency overrides, native patches, polyfills. But once it is running, the developer experience is excellent: observable queries, lazy-loaded relations, and a sync protocol that forces you to think about conflicts instead of ignoring them.

The landscape is moving fast. PowerSync is solving the "I do not want to build a sync server" problem well. ElectricSQL + TanStack DB is the most exciting open-source path. WatermelonDB's maintenance pace is a real concern — if you are starting fresh today, evaluate all three.

But if you need full control, zero vendor dependency, and you have the backend team to build the sync — WatermelonDB still earns its place. You just needed this guide to get past the setup.

🧪 Demo Project

Clone the repo, run it, break it. The entire working implementation from this article is there — Expo API routes, WatermelonDB setup, sync hooks, models, schema, all of it.

github.com/FastheDeveloper/watermelondb-expo-offline-demo

git clone https://github.com/FastheDeveloper/watermelondb-expo-offline-demo.git
cd watermelondb-expo-offline-demo
npm install
npx expo run:ios   # or npx expo run:android

If you find a setup issue not covered here, open an issue and I will update this guide. 🙏

Find me on Twitter/X and LinkedIn. I write about React Native architecture, offline-first patterns, and the things tutorials skip over.

🎥 Mastering Media Uploads in React Native — Images, Videos & Smart Compression (2026 Guide)

Farouq Seriki — Wed, 12 Nov 2025 12:55:38 +0000

If you’ve ever built a media-heavy app, you know the struggle.

A user snaps a gorgeous 4K video or a 12MP selfie and — boom — your upload queue explodes, your backend times out, and someone tweets,

“Your app just crashed 😭”

Between different camera APIs, resolutions, and codecs, file sizes can jump from a few KB to hundreds of MB.

And simply compressing once often isn’t enough.

💡 The smarter fix:

Set strict upload limits (e.g., ≤ 2 MB for images, ≤ 20 MB for video) and iteratively compress each file until it fits the cap — all on-device.

Add good UX (progress bars, cancel buttons, smart defaults) and you’ll deliver silky-smooth uploads even on slow connections.

🧭 Table of Contents

Why Compression Matters
Quick Reference: Library Compatibility
React Native CLI Setup (Images & Video)
Expo Setup
Full Image Compression & Upload Example
Full Video Compression & Upload Example
Iterative Compression Pattern
Permissions & Troubleshooting
Production Tips
Final Thoughts

🎯 Why Compression Matters

Slow uploads & timeouts: mobile networks drop large requests.
Data cost: users burn bandwidth fast.
Server load: big files inflate storage and CDN bills.
UX: decoding large media tanks memory and drains battery.

Goal: compress client-side until it fits the backend’s file-size threshold.

⚡ Quick Reference: Library Compatibility

Library	Min React Native Version	Notes
react-native-video v6	≥ 0.68.2 (RN 0.73 uses iOS 13+)	iOS ≥ 13.0 required from 6.0.0-beta.8
react-native-fs	≥ 0.61 → use `@2.16.0+`	Native file access & utilities
react-native-image-picker	Works ≥ 0.60	Handles photos & videos
react-native-compressor	Works ≥ 0.65	Local media compression

⚙️ React Native CLI Setup (Images & Video)

We’ll use:

Package	Purpose	Docs
`react-native-image-picker`	Pick or capture photos & videos
`react-native-compressor`	Compress images/videos efficiently
`react-native-fs`	File size utilities & uploads
`react-native-video`	Full-control video player

🧩 Installation

npx @react-native-community/cli@latest init MediaUploadRN
cd MediaUploadRN

npm install react-native-image-picker react-native-compressor react-native-fs react-native-video
cd ios && pod install && cd ..

⚠️ `react-native-fs` Version Compatibility

React Native Version	Install This Version
< 0.57 / Gradle < 3	`react-native-fs@2.11.17`
≥ 0.57 / Gradle ≥ 3	`react-native-fs@2.13.2+`
≥ 0.61 ✅	`react-native-fs@2.16.0+`

npm install react-native-fs@2.16.0
# RN < 0.60 only:
npx react-native link react-native-fs

CocoaPods (iOS):

pod 'RNFS', :path => '../node_modules/react-native-fs'
pod install

🎬 React Native Video (v6.0.0+) Setup

⚠️ V6.0.0 Information

Version 6 introduces modern architecture & performance improvements.

Requires React Native ≥ 0.68.2

From 6.0.0-beta.8 → requires iOS ≥ 13.0 (default in RN 0.73).

For older RN projects, stick with react-native-video@5.2.x.

📦 Installation

npm install react-native-video
# or
yarn add react-native-video

📱 iOS Setup

cd ios && pod install && cd ..

Minimum: iOS 13 | RN 0.68.2+

Enable Custom Features (Podfile)

Video Caching:

$RNVideoUseVideoCaching=true

Google IMA (ads):

$RNVideoUseGoogleIMA=true

If caching is enabled, also add to Gemfile:

gem "cocoapods-swift-modular-headers"

and run:

bundle install
bundle exec pod install

🤖 Android Setup

Your project must use Kotlin ≥ 1.8 and compileSdk 34:

buildscript {
    ext.kotlinVersion = '1.8.0'
    ext.compileSdkVersion = 34
    ext.targetSdkVersion = 34
}

Optional ExoPlayer flags (android/build.gradle):

buildscript {
  ext {
    useExoplayerHls = true
    useExoplayerDash = true
    useExoplayerSmoothStreaming = true
    useExoplayerIMA = false // enable if ads needed
    useExoplayerRtsp = false
  }
}

✅ Default enabled: SmoothStreaming, Dash, HLS
⚠️ Each feature adds size — enable only what you need.

📱 Android Permissions

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<!-- For older SDKs -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

🍎 iOS Permissions

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your library to select media.</string>
<key>NSCameraUsageDescription</key>
<string>We need access to your camera to capture media.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone for video audio.</string>

🖼 React Native Cli Image Compression & Upload Example

import React, { useState } from "react";
import {
  View,
  Button,
  Image,
  Alert,
  ScrollView,
  StyleSheet,
} from "react-native";
import * as ImagePicker from "react-native-image-picker";
import { Image as ImageCompressor } from "react-native-compressor";
import RNFS from "react-native-fs";

const IMAGE_MAX_BYTES = 2 * 1024 * 1024; // 2 MB
const UPLOAD_URL = "https://your.api/uploads";

async function getFileSize(uri: string) {
  const stat = await RNFS.stat(uri.replace("file://", ""));
  return Number(stat.size || 0);
}

async function compressImageUntilUnder(uri: string, maxBytes: number) {
  let quality = 0.8;
  let currentUri = uri;
  for (let i = 0; i < 5; i++) {
    const compressed = await ImageCompressor.compress(currentUri, {
      compressionMethod: "auto",
      quality,
    });
    const size = await getFileSize(compressed);
    if (size <= maxBytes) return compressed;
    quality = Math.max(0.3, quality - 0.15);
    currentUri = compressed;
  }
  return currentUri;
}

async function uploadFile(uri: string) {
  const form = new FormData();
  form.append("image", {
    // @ts-ignore
    uri,
    name: "upload.jpg",
    type: "image/jpeg",
  });
  await fetch(UPLOAD_URL, { method: "POST", body: form });
}

export default function ImageUploader() {
  const [uri, setUri] = useState<string | null>(null);
  const [compressedUri, setCompressedUri] = useState<string | null>(null);

  const pickImage = async () => {
    const res = await ImagePicker.launchImageLibrary({ mediaType: "photo" });
    if (res.didCancel || !res.assets) return;
    setUri(res.assets[0].uri ?? null);
  };

  const handleUpload = async () => {
    if (!uri) return Alert.alert("Pick an image first");
    const compressed = await compressImageUntilUnder(uri, IMAGE_MAX_BYTES);
    setCompressedUri(compressed);
    await uploadFile(compressed);
    Alert.alert("Upload complete!");
  };

  return (
    <ScrollView contentContainerStyle={styles.container}>
      <Button title="Pick Image" onPress={pickImage} />
      {uri && <Image source={{ uri }} style={styles.img} />}
      <Button title="Compress & Upload" onPress={handleUpload} />
      {compressedUri && (
        <Image source={{ uri: compressedUri }} style={styles.img} />
      )}
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: { padding: 20, gap: 16 },
  img: { height: 250, resizeMode: "contain", backgroundColor: "#eee" },
});

🎥 React Native Cli Video Compression & Upload Example

import React, { useState } from "react";
import { View, Button, Text, Alert, StyleSheet } from "react-native";
import * as ImagePicker from "react-native-image-picker";
import { Video as VideoCompressor } from "react-native-compressor";
import RNFS from "react-native-fs";
import Video from "react-native-video";

const VIDEO_MAX_BYTES = 20 * 1024 * 1024; // 20 MB
const UPLOAD_URL = "https://your.api/uploads";

async function getFileSize(uri: string) {
  const stat = await RNFS.stat(uri.replace("file://", ""));
  return Number(stat.size || 0);
}

async function compressVideoUntilUnder(
  uri: string,
  maxBytes: number,
  onProgress?: (p: number) => void
) {
  const presets: Array<"auto" | "medium" | "low"> = ["auto", "medium", "low"];
  let currentUri = uri;
  for (const preset of presets) {
    const compressed = await VideoCompressor.compress(
      currentUri,
      { compressionMethod: preset },
      (p) => onProgress?.(Math.round(p * 100))
    );
    const size = await getFileSize(compressed);
    if (size <= maxBytes) return compressed;
    currentUri = compressed;
  }
  return currentUri;
}

async function uploadVideo(uri: string) {
  const form = new FormData();
  form.append("video", {
    // @ts-ignore
    uri,
    name: "video.mp4",
    type: "video/mp4",
  });
  await fetch(UPLOAD_URL, { method: "POST", body: form });
}

export default function VideoUploader() {
  const [uri, setUri] = useState<string | null>(null);
  const [compressedUri, setCompressedUri] = useState<string | null>(null);
  const [progress, setProgress] = useState<number | null>(null);

  const pickVideo = async () => {
    const res = await ImagePicker.launchImageLibrary({ mediaType: "video" });
    if (res.didCancel || !res.assets) return;
    setUri(res.assets[0].uri ?? null);
  };

  const handleUpload = async () => {
    if (!uri) return Alert.alert("Pick a video first");
    const compressed = await compressVideoUntilUnder(
      uri,
      VIDEO_MAX_BYTES,
      setProgress
    );
    setCompressedUri(compressed);
    await uploadVideo(compressed);
    Alert.alert("Upload complete!");
    setProgress(null);
  };

  return (
    <View style={styles.container}>
      <Button title="Pick Video" onPress={pickVideo} />
      {progress != null && <Text>Compressing: {progress}%</Text>}
      <Button
        title="Compress & Upload"
        onPress={handleUpload}
        disabled={progress != null}
      />
      {compressedUri && (
        <Video
          source={{ uri: compressedUri }}
          style={styles.video}
          controls
          paused
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { padding: 20, gap: 16 },
  video: { height: 220, backgroundColor: "#000" },
});

⚙️ Expo Setup — Capture, Compress & Upload Media

Expo makes working with media surprisingly straightforward — whether you’re handling simple image uploads or full video workflows.
You can choose between two reliable approaches depending on your project type:

🖼 Image Compression Only (Pure Expo) — works entirely inside the Managed Workflow using expo-image-manipulator.
🎥 Video Compression (Dev Build Mode) — unlocks native-level compression and playback with react-native-compressor, react-native-fs, and react-native-video.

Both methods deliver efficient, on-device compression — no backend preprocessing required.

🖼 Image Compression Only — Expo Image Manipulator

If you’re building with Pure Expo (Managed Workflow), you can compress and resize images directly on the device using expo-image-manipulator.
This library is fast, stable, and ideal for reducing image size before uploads — perfect for profile photos, product images, or gallery uploads.

⚙️ Installation

npx expo install expo-image-manipulator expo-file-system expo-image-picker

💻 Example — Dynamic Image Compression & Resizing

The example below dynamically compresses any selected image to stay under a custom file-size limit (e.g., 2 MB, 5 MB, 10 MB).
It progressively reduces quality and resolution until the image meets the target threshold — all on-device.

import React, { useEffect, useState } from "react";
import {
  View,
  Text,
  StyleSheet,
  Button,
  ActivityIndicator,
  Image,
  Alert,
} from "react-native";
import * as ImagePicker from "expo-image-picker";
import * as FileSystem from "expo-file-system";
import { useImageManipulator, SaveFormat } from "expo-image-manipulator";

const DEFAULT_COMPRESSION_QUALITY = 0.8;
const MIN_QUALITY = 0.3;
const DOWNSCALE_FACTOR = 0.85;

// ---------- File Size Utilities ----------
const getFileSize = async (uri: string): Promise<number> => {
  const info = await FileSystem.getInfoAsync(uri);
  return info.size || 0;
};

const formatFileSize = (bytes: number) =>
  `${(bytes / 1024 / 1024).toFixed(2)} MB`;

// ---------- Dynamic Compression Logic ----------
const compressImageUntilUnder = async (
  uri: string,
  manipulator: ReturnType<typeof useImageManipulator>,
  maxSizeMB: number
): Promise<string> => {
  try {
    const MAX_FILE_SIZE = maxSizeMB * 1024 * 1024;
    let quality = DEFAULT_COMPRESSION_QUALITY;
    let currentUri = uri;
    let currentSize = await getFileSize(uri);
    let width: number | undefined;
    let height: number | undefined;

    console.log(
      `📸 Starting compression: ${formatFileSize(
        currentSize
      )} (limit ${maxSizeMB} MB)`
    );

    while (currentSize > MAX_FILE_SIZE && quality > MIN_QUALITY) {
      if (width || height) manipulator.resize({ width, height });
      const rendered = await manipulator.renderAsync();
      const compressed = await rendered.saveAsync({
        compress: quality,
        format: SaveFormat.JPEG,
      });

      const newSize = await getFileSize(compressed.uri);
      console.log(`→ ${formatFileSize(newSize)} @ quality ${quality}`);

      if (newSize > MAX_FILE_SIZE) {
        quality *= 0.8;
        width = (rendered.width || 0) * DOWNSCALE_FACTOR;
        height = (rendered.height || 0) * DOWNSCALE_FACTOR;
        currentUri = compressed.uri;
        currentSize = newSize;
      } else {
        console.log(`✅ Final size under ${maxSizeMB} MB`);
        return compressed.uri;
      }
    }

    console.warn(
      `⚠️ Could not compress below ${maxSizeMB} MB — returning best result.`
    );
    return currentUri;
  } catch (err) {
    console.error("Compression error:", err);
    return uri;
  }
};

// ---------- Compression Overlay ----------
const ImageCompressor = ({
  uri,
  onComplete,
  maxSizeMB,
}: {
  uri: string;
  onComplete: (resultUri: string) => void;
  maxSizeMB: number;
}) => {
  const manipulator = useImageManipulator(uri);
  const [isCompressing, setIsCompressing] = useState(false);

  useEffect(() => {
    const compress = async () => {
      setIsCompressing(true);
      try {
        const originalSize = await getFileSize(uri);
        console.log("Original size:", formatFileSize(originalSize));

        const rendered = await manipulator.renderAsync();
        const temp = await rendered.saveAsync({
          compress: DEFAULT_COMPRESSION_QUALITY,
          format: SaveFormat.JPEG,
        });

        const firstPassSize = await getFileSize(temp.uri);
        let finalUri = temp.uri;

        if (firstPassSize > maxSizeMB * 1024 * 1024) {
          finalUri = await compressImageUntilUnder(
            temp.uri,
            manipulator,
            maxSizeMB
          );
        }

        const finalSize = await getFileSize(finalUri);
        console.log("✅ Final compressed size:", formatFileSize(finalSize));

        onComplete(finalUri);
      } catch (e) {
        console.error(e);
        onComplete(uri);
      } finally {
        setIsCompressing(false);
      }
    };
    compress();
  }, [uri]);

  if (!isCompressing) return null;

  return (
    <View style={styles.overlay}>
      <ActivityIndicator size="large" color="#0F6B2D" />
      <Text style={styles.overlayText}>Compressing image...</Text>
    </View>
  );
};

// ---------- Main Component ----------
export default function ExpoImageCompressor() {
  const [imageUri, setImageUri] = useState<string | null>(null);
  const [finalUri, setFinalUri] = useState<string | null>(null);
  const [maxSizeMB, setMaxSizeMB] = useState<number>(2); // dynamic user limit

  const pickImage = async () => {
    const res = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ImagePicker.MediaTypeOptions.Images,
      allowsEditing: true,
      quality: 1,
    });
    if (!res.canceled) {
      setImageUri(res.assets[0].uri);
    }
  };

  return (
    <View style={styles.container}>
      <Button title="Pick Image" onPress={pickImage} />
      {imageUri && <Image source={{ uri: imageUri }} style={styles.img} />}
      <Text style={styles.label}>Max Size: {maxSizeMB} MB</Text>

      {imageUri && (
        <ImageCompressor
          uri={imageUri}
          maxSizeMB={maxSizeMB}
          onComplete={(uri) => {
            setFinalUri(uri);
            Alert.alert("✅ Compression complete!");
          }}
        />
      )}

      {finalUri && <Image source={{ uri: finalUri }} style={styles.img} />}
    </View>
  );
}

// ---------- Styles ----------
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    padding: 20,
  },
  img: { width: "90%", height: 250, marginTop: 20, borderRadius: 12 },
  label: { marginTop: 16, fontSize: 16, color: "#333" },
  overlay: {
    ...StyleSheet.absoluteFillObject,
    backgroundColor: "rgba(0,0,0,0.7)",
    justifyContent: "center",
    alignItems: "center",
  },
  overlayText: { color: "white", marginTop: 12 },
});

🧠 Why It Works

Dynamic Limit: Easily change the size cap (maxSizeMB) for different use cases (e.g., 2 MB for avatars, 10 MB for photos).
Iterative Compression: Reduces both quality and resolution in steps until under the defined limit.
Expo-Only: Runs fully in JavaScript — no native linking or prebuild required.
Real-World Safe: Handles large images gracefully and provides user feedback with an activity overlay.
Reusable: Drop into any project — just pass a maxSizeMB value and a completion callback.

🎥 Video Compression — Dev Build Mode

If your app needs to handle video uploads or large media files, switch to an Expo Dev Build.
This mode enables access to native libraries for true on-device compression, caching, and playback.

⚙️ Installation

npm install react-native-compressor react-native-fs react-native-video
npx expo prebuild
npx expo run:android
# or
npx expo run:ios

Once complete, your project will have native access to efficient compression and smooth video rendering.

💻 Example — Dynamic Video Compression Helper

import { Video as VideoCompressor } from "react-native-compressor";
import RNFS from "react-native-fs";

/**
 * Compresses a video dynamically until it fits under the given size (in MB).
 * Supports both Expo Dev Build and React Native CLI setups.
 */
export async function compressVideoUntilUnder(
  uri: string,
  maxSizeMB: number,
  onProgress?: (p: number) => void
): Promise<string> {
  try {
    const maxBytes = maxSizeMB * 1024 * 1024;
    const presets: Array<"auto" | "medium" | "low"> = ["auto", "medium", "low"];
    let currentUri = uri;

    const getFileSize = async (fileUri: string): Promise<number> => {
      const stat = await RNFS.stat(fileUri.replace("file://", ""));
      return Number(stat.size || 0);
    };

    let currentSize = await getFileSize(currentUri);
    console.log(
      `🎬 Original size: ${(currentSize / 1024 / 1024).toFixed(2)} MB`
    );

    for (const preset of presets) {
      console.log(`⚙️ Trying preset: ${preset}`);
      const compressed = await VideoCompressor.compress(
        currentUri,
        { compressionMethod: preset },
        (progress) => onProgress?.(Math.round(progress * 100))
      );

      const newSize = await getFileSize(compressed);
      console.log(`→ ${formatSize(newSize)} after ${preset}`);

      if (newSize <= maxBytes) {
        console.log(`✅ Final size under ${maxSizeMB} MB`);
        return compressed;
      }

      currentUri = compressed;
      currentSize = newSize;
    }

    console.warn(
      `⚠️ Could not compress below ${maxSizeMB} MB — returning best result.`
    );
    return currentUri;
  } catch (err) {
    console.error("❌ Compression failed:", err);
    return uri;
  }
}

const formatSize = (bytes: number) => `${(bytes / 1024 / 1024).toFixed(2)} MB`;

✅ What You Unlock

Library	Purpose
react-native-compressor	Efficient on-device video and image compression
react-native-fs	File-size inspection, local reads/writes, and uploads
react-native-video	Smooth playback, caching, and adaptive streaming

📘 Note: Expo Dev Builds fully support config plugins, allowing features like caching and streaming exactly like a bare React Native project.

🧩 Summary

🖼 Pure Expo (Managed Workflow): Use expo-image-manipulator for image compression — 100% JavaScript, no native build needed.
🎥 Dev Build Mode (Native): Use react-native-compressor and react-native-video for professional-grade video compression and playback.

Both approaches help you deliver faster uploads, smaller files, and better mobile UX — all while staying true to Expo’s developer-friendly workflow.

🔁 Iterative Compression Pattern

while (size(uri) > limit && attempts < MAX_ATTEMPTS) {
  uri = compress(uri, nextParams());
}

Ensures consistent output sizes across devices.

🧰 Permissions & Troubleshooting

Android 13+: READ_MEDIA_IMAGES, READ_MEDIA_VIDEO
Older Android: READ_EXTERNAL_STORAGE
iOS: NSCameraUsageDescription, NSPhotoLibraryUsageDescription, NSMicrophoneUsageDescription
Always check file size after compression — Android content:// URIs can differ.
Test on real devices; emulators lack cameras and true codecs.

🏗 Production Tips

Enforce size limits in the backend too.
Resize before compressing (e.g., 1920 px width cap).
Adjust compression by connection type (Wi-Fi vs cellular).
Generate thumbnails for video feeds.
Keep compression async — never block the UI.

✅ Final Thoughts

Compression isn’t just a backend optimization — it’s a user-experience feature.
By iteratively compressing files, tracking progress, and configuring each library correctly (especially React Native Video v6 and react-native-fs), you’ll keep uploads fast, consistent, and reliable across every device.

💬 If this guide helped, drop a ❤️ or share your own setup for React Native media uploads.

React Native Dynamic App Icons

Farouq Seriki — Mon, 23 Sep 2024 07:14:33 +0000

This article demonstrates a practical implementation of dynamic app icon changing in React Native, utilising the react-native-change-icon library. It serves as a guide and example for developers looking to incorporate icon-switching functionality into their iOS and Android applications.

Github Repository

Article Highlights

Practical Implementation: Shows how to integrate and use the react-native-change-icon library in a real-world scenario.
Cross-Platform Demo: Includes examples for both iOS and Android platforms.
Step-by-Step Guide: Provides a clear walkthrough of the implementation process.

Benefits of Dynamic App Icons

Enhanced User Experience: Allows for a customisable and fresh app appearance.
Increased Engagement: Can be used to highlight new features, events, or campaigns.
Seasonal Adaptability: Demonstrates how to update the app's look for holidays or special occasions.
Marketing Tool: Shows potential for A/B testing different icon designs.

Installation

Install react-native-change-icon into your react native project using
yarn add react-native-change-icon or npm i react-native-change-icon
Generate your AppIcons using AppIconGenerator

Sample Icons are in the ./images folder import into the app icon generator and generate app icons for iPhone and Android( you can create for all operating systems)

`Android`

Open generated zip folder, navigate to android folder and rename all icons to desired name

`ios`

Open the generated zip folder, navigate to ios folder and rename the AppIcon.appiconset to desired icon name

Edit Contents.json and change the Assets.xcassets/AppIcon.appiconset to new Icon name e.g. Images.xcassets/HarpIcons.appiconset

REPEAT ABOVE STEPS FOR ALL OTHER ICONS

Android: Drag all of the mipmap folders into android/app/src/main/res/

ios : Drag all of the .appiconset folders into ios//Images.xcassets

Environment Setup

`Android`

Add an alias for each of your new icons within the AndroidManifest.xml (within ).

  - Make sure these have the properties as shown below.
  - Create an alias for .MainActivityDefault as well but for this, set android:enabled="true".
  - For the name prefix it .MainActivity... followed by the name you will use to reference your icon. e.g. for our HarpIcons icon we will use .MainActivityHarpIcons

`ios`

At the bottom of your Info.plist insert a key for CFBundleIcons.
Within this dictionary add another key for CFBundleAlternateIcons
In XCode, in your app's General settings, under App Icons and Launch Screen, set "App Icon" to Default and check the "Include all app icon assets" checkbox below.
Finally then within this dictionary you can add in the keys for you new icons

  - The key is the name you will reference from within code.
  - Set the first array item to the name of the .appiconset we created earlier.

Usage

To use the changeIcon functionality, simply import it along with any other required methods from the library:



import { changeIcon, getIcon, resetIcon } from 'react-native-change-icon';

// Pass the name of icon to be enabled
changeIcon('HarpIcons');

That's it! You can now seamlessly change icons based on your implementation logic.

Troubleshooting and Common Issues

When implementing react-native-change-icon, especially in an Expo-managed project, you might encounter some challenges. Here are solutions to common problems:

Accessing Native iOS and Android Files in Expo

Problem: Expo-managed projects don't have direct access to native iOS and Android files by default.
Solution: Use the prebuild command to generate native projects:



expo prebuild

This command creates ios and android folders in your project, allowing you to modify native files as needed for icon changing functionality.
Note: After running prebuild, your project becomes an Expo "bare" workflow project. Be sure to commit these changes to version control.

Testing Production Builds on iOS

Problem: Testing icon changing in a production environment on iOS requires a release build.
Solution: Use the following command to create and run a release build on an iOS device:



npx expo run:ios --configuration Release --device

This command:
Builds your app in release configuration
Installs it on a connected iOS device
Allows you to test icon changing functionality in a production-like environment

Testing Production Builds on Android

Problem: Testing icon changing in a production environment on Android requires a release APK.
Solution: Follow these steps to create and test a release APK

Navigate to the android directory in your project:



cd android

Run the Gradle task to assemble the release APK:



./gradlew assembleRelease

The APK will be generated in android/app/build/outputs/apk/release/app-release.apk Install the APK on your Android device or emulator to test the icon changing functionality in a production environment.

Server Defined Rendering for React Native Using Rise

Farouq Seriki — Wed, 11 Sep 2024 09:34:51 +0000

Server Repository : https://github.com/FastheDeveloper/react-native-rise-sdui-server
Mobile Repository : https://github.com/FastheDeveloper/react-native-rise-sdui-mobile

🚀 Introduction

This article contains the implementation for Server-Driven UI (SDUI) development using Rise Tools. It's designed to seamlessly update React Native applications, providing dynamic UI components that can be updated in production without rebuilding or redeploying your app.

🎯 What You'll Learn

Core principles of Server Defined Rendering for React Native
Server Defined Rendering VS OTA updates Vs Update Prompts
Rise Tools Architecture
Creating Server side
Creating Client side app
Building mobile app for installation
Deploying backend server and using it to update the mobile app

🛠 Prerequisites

Before diving in, make sure you have:

A basic understanding of JavaScript, Typescript and React Native
Node.js and npm installed on your development machine
Make sure you have completed the React Native - Environment Setup instructions
A basic knowlwdge of Tamagui

📚 Tutorial Sections

Introduction to Server-Driven Development
- Definition and core concepts of Server-Driven UI (SDUI)
- Benefits and use cases for SDUI
- Real-world examples of apps utilizing SDUI and their success stories
Setting Up Rise Server
- Project setup & folder structure
- Server configuration and initialization
- Creating Base HomeScreen Model
Setting Up Your Expo Project
- Cloning existing expo template
- Creating a new Expo project
- Essential configurations and dependencies
- Integrating the HomeScreen model from the server
Updating React Native Application with Server update
Deploying the Server to Production
Dynamic React Native App Updates from Server
Building and Testing the Mobile App for Production

Introduction to Server-Driven Development

Definition and core concepts of Server-Driven UI (SDUI):
SDUI is an architectural pattern where the server defines and controls the user interface of a client application. Instead of hardcoding UI elements in the client, the server sends a UI specification (often in JSON format) that the client interprets and renders. This approach allows for dynamic UI updates without requiring app updates.

Key concepts include:

UI specification: A structured description of the interface layout and components
Client-side renderer: A component that interprets the specification and creates native UI elements
Dynamic updates: The ability to change the UI by modifying the server-side specification

Benefits and use cases for SDUI:

Flexibility: Easily update UI without app store releases
Consistency: Maintain a uniform experience across platforms
A/B testing: Quickly test different layouts or features
Personalization: Tailor UI based on user segments or behaviors
Rapid iteration: Implement UI changes faster
Feature flags: Enable or disable features remotely
Reduced app size: Some UI logic moves to the server

Why Server Defined Rendering is Superior to Over-The-Air updates and Update Prompts

Instant Updates: Unlike OTA updates or update prompts, SDR ensures all users are always on the latest version, eliminating fragmentation and version compatibility issues.
Improved User Experience: SDR removes the need for intrusive update prompts or download waiting times, providing a seamless experience.
Enhanced Security and Control: With logic on the server, SDR offers better protection against reverse engineering and unauthorized modifications.
Flexibility and Agility: SDR allows for rapid iterations and A/B testing without the need for app store approvals or user actions.
Reduced Client-Side Complexity: By moving logic to the server, SDR simplifies client-side code, potentially improving app performance and reducing bugs.
Data-Driven Improvements: With all users on the same version, it's easier to gather consistent analytics and make data-driven decisions.

Setting Up Rise Server

We will work with this UI focusing on creating a server-side UI and implementing it in a React Native application. Follow the tutorial sections to build your SDUI-powered app step by step.

Setting Up Rise Server

To create a new Rise server project, follow these steps:

Open your terminal.
Run the following command: npm create rise@latest

This is the resulting folder structure



my-rise-project/
├── node_modules
├── src/
│ ├── models.tsx
│ ├── server.ts
├── package.json
├── tsconfig.json
└── README.md

Setting up Server for Home screen

Create a HomeScreen.tsx file in your preferred directory, and let's get started.



import {
    H1,
    H3,
    H6,
    Text,
    XStack,
    YStack,
} from "@rise-tools/kitchen-sink/server";

export const models = {
    HeaderUI,
    SearchUI,
    NearbyUi: NearbyUi,
    BannerUi,
    ProductUi,
    HomeScreen,
};

function HeaderUI() {
    return (
        <YStack>
            <Text>Header Ui</Text>
        </YStack>
    );
}

function SearchUI() {
    return (
        <YStack>
            <H1>Search Ui</H1>
        </YStack>
    );
}

function NearbyUi() {
    return (
        <YStack>
            <H3>Nearby resturants</H3>

            <XStack gap="$12">
                <H6>Nearest resturants</H6>
            </XStack>
        </YStack>
    );
}

function BannerUi() {
    return (
        <YStack>
            <H1>Banner</H1>
        </YStack>
    );
}

function ProductUi() {
    return (
        <YStack>
            <Text>Our Top Product</Text>
            <XStack gap="$8">
                <Text>🌚</Text>
                <Text>🌚</Text>
                <Text>🌚</Text>
                <Text>🌚</Text>
                <Text>🌚</Text>
            </XStack>
        </YStack>
    );
}

function TripUi() {
    return (
        <YStack gap="$8">
            <Text>Your Trips</Text>
            <Text>🌚</Text>
            <Text>🌚</Text>
            <Text>🌚</Text>
            <Text>🌚</Text>
            <Text>🌚</Text>
        </YStack>
    );
}

function HomeScreen() {
    return (
        <YStack>
            <HeaderUI />
            <SearchUI />
            <NearbyUi />
            <BannerUi />
            <ProductUi />
            <TripUi />
        </YStack>
    );
}

Models Object:

An object named models is exported, containing references to various UI components. This object is used for dynamic rendering and to organize components for easier access.

This component breaks down the HomeScreen into several distinct components: HeaderUi, SearchUi, NearbyUi, BannerUi, ProductUi, and TripUi. These components can be used individually on the mobile/client side or combined to form the complete HomeScreen. By using the main HomeScreen in the client app, we can dynamically rearrange its structure from the server.

Setting Up `server.ts`



import { setupRiseTools } from "@rise-tools/cli";
import { createWSServer } from "@rise-tools/server";

import { models as mainModal } from "~src/home/home"; // import models from `Homescreen.tsx`
const port = Number(process.env.PORT || "3015");

const models = { ...mainModal };
const server = createWSServer(models, port);

if (process.env.NODE_ENV === "development") {
    setupRiseTools({ server });
}

Setting Up Your Expo Project

Cloning existing expo template

To quickly get started with your application, you can clone this base repository, which is set up with Expo, expo-router, Tamagui, and Rise Tools.

Run the following command to clone the repository:



git clone git@github.com:rise-tools/rise-mobile-quickstart.git

Manual set Up

To set up your project with Tamagui and Expo Router, run the following command:



npx create-expo-stack@latest react-native-rise-sdui-mobile --expo-router --tamagui

Then, install the necessary dependencies:

@rise-tools/kit-expo-router
@rise-tools/kitchen-sink
@rise-tools/react
@rise-tools/ws-client
expo-haptics

Create modelSource.ts

Next, create a modelSource.ts file to define the connection to the WebSocket server provided by the server.



import { createWSModelSource } from "@rise-tools/ws-client";

export const modelSource = createWSModelSource("ws://192.168.0.213:3015"); //switch 192.168.0.213 with your expo localhost url

Create riseActions.ts

Create a riseActions.ts file to define the local action library for the app.



import { useExpoRouterActions } from "@rise-tools/kit-expo-router";
import {
    useHapticsActions,
    useLinkingActions,
    useToastActions,
} from "@rise-tools/kitchen-sink";

export function useRiseActions() {
    return {
        ...useHapticsActions(),
        ...useLinkingActions(),
        ...useToastActions(),
        ...useExpoRouterActions(),
    };
}

Create riseComponenets.ts

Create a riseComponents.ts file to define the local component library for the app.




import {
    FormComponents,
    LucideIconsComponents,
    QRCodeComponents,
    RiseComponents,
    SVGComponents,
    TamaguiComponents,
    } from '@rise-tools/kitchen-sink';

export const components = {
    ...FormComponents,
    ...LucideIconsComponents,
    ...QRCodeComponents,
    ...RiseComponents,
    ...SVGComponents,
    ...TamaguiComponents,
    };

Integrating the HomeScreen model from the server

In the server terminal, run Server with npm run dev to start the server
In the react native app terminal, run the app using the following commands:
yarn ios to open the app on an iOS simulator
yarn android to open the app on an Android emulator
yarn start to open the app with Expo on your physical device
In the appropriate Expo file, set up your HomeScreen to utilize Rise tools by calling the models defined for the HomeScreen:



import { Rise } from '@rise-tools/react';
import { Stack, Link } from 'expo-router';
import { View } from 'react-native';

import { Button } from '~/components/Button';
import { Container } from '~/components/Container';
import { ScreenContent } from '~/components/ScreenContent';
import { modelSource } from '~/src/modelSource';
import { useRiseActions } from '~/src/riseActions';
import { components } from '~/src/riseComponents';

export default function Home() {
  return (
    <>
      <Rise
        modelSource={modelSource}
        components={components}
        path="HomeScreen" //model gotten from the server
        actions={useRiseActions()}
      />
    </>
  );
}

Updating React Native Application with Server update

While the server is running, any changes made to the Homescreen model will be automatically reflected in the mobile application.



function HeaderUI() {
    return (
        <XStack
            alignItems={"center"}
            padding={"$2"}
            justifyContent={"space-between"}>
            <XStack>
                <UserIcon width={70} height={60} />
                <XStack alignItems={"center"}>
                    <YStack>
                        <Text color={"#838282"}>Hello,</Text>
                        <H3 color={"#0F0F0F"} fontWeight={"700"}>
                            F.A.S
                        </H3>
                    </YStack>
                </XStack>
            </XStack>

            <Hamburger width={32} height={32} />
        </XStack>
    );
}

To finalize the design, we'll update the other components in our homescreen component, which will automatically update the app.



import {
    H3,
    H6,
    H5,
    RiseForm,
    Text,
    XStack,
    YStack,
    InputField,
} from "@rise-tools/kitchen-sink/server";

import {
    UserIcon,
    Hamburger,
    SearchIcon,
    MicIcon,
    SmallFork,
    RightIcon,
    ClockIcon,
    StarIcon,
    CarIcon,
    PackageIcon,
    ErrandIcon,
    Ridesicon,
    ResturantIcon,
} from "~/components/UserIcon";

export const models = {
    HeaderUI,
    SearchUI,
    NearbyUi: NearbyUi,
    BannerUi,
    ProductUi,
    HomeScreen,
};

const myProducts = [
    {
        name: "Package",
        icon: <PackageIcon width={32} height={32} />,
    },
    {
        name: "Rides",
        icon: <Ridesicon width={35} height={32} />,
    },
    {
        name: "Errands",
        icon: <ErrandIcon width={32} height={32} />,
    },
    {
        name: "Resturant",
        icon: <ResturantIcon width={32} height={32} />,
    },
];
function HeaderUI() {
    return (
        <XStack
            alignItems={"center"}
            padding={"$2"}
            justifyContent={"space-between"}>
            <XStack>
                <UserIcon width={70} height={60} />
                <XStack alignItems={"center"}>
                    <YStack>
                        <Text color={"#838282"}>Hello,</Text>
                        <H3 color={"#0F0F0F"} fontWeight={"700"}>
                            F.A.S
                        </H3>
                    </YStack>
                </XStack>
            </XStack>

            <Hamburger width={32} height={32} />
        </XStack>
    );
}

function SearchUI() {
    return (
        <XStack alignItems={"center"}>
            <SearchIcon width={20} height={20} />
            <RiseForm onSubmit={() => {}} flex={1} justifyContent={"center"}>
                <InputField
                    id="searchInput"
                    backgroundColor={"#fff"}
                    borderWidth={0}
                    borderRadius={0}
                    height={40}
                    style={{ marginTop: -14 }}
                    placeholder={"Where are you going?"}
                    placeholderTextColor={"#838282"}
                    color={"black"}
                />
            </RiseForm>
            <MicIcon width={20} height={20} />
        </XStack>
    );
}

function NearbyUi() {
    return (
        <YStack marginTop={"$4"} gap={"$2"}>
            <XStack alignItems={"flex-end"} justifyContent={"space-between"}>
                <H3 color={"black"} fontWeight={"500"}>
                    Nearby Resturants
                </H3>
                <H3 color={"#838282"} fontSize={20}>
                    See all
                </H3>
            </XStack>

            <XStack justifyContent={"space-between"} alignItems={"center"}>
                <XStack gap={"$2"} alignItems={"center"}>
                    <SmallFork width={34} height={34} />
                    <YStack gap={"$2"}>
                        <H6 color={"#000"} fontWeight={"500"}>
                            The Place Restaurant
                        </H6>
                        <XStack gap={"$4"} alignItems={"center"}>
                            <XStack gap={"$2"}>
                                <ClockIcon width={16} height={16} />
                                <Text color={"#838282"}>5mins drive</Text>
                            </XStack>
                            <XStack gap={"$2"}>
                                <StarIcon width={16} height={16} />
                                <Text color={"#838282"}>4.5</Text>
                            </XStack>
                        </XStack>
                    </YStack>
                </XStack>
                <RightIcon width={24} height={24} />
            </XStack>
        </YStack>
    );
}

function BannerUi() {
    return (
        <XStack
            backgroundColor={"#24B229"}
            alignItems={"center"}
            justifyContent={"space-between"}
            paddingHorizontal={"$4"}
            marginVertical={"$4"}
            borderRadius={15}>
            <YStack>
                <Text fontSize={20} color={"white"} fontWeight={"500"}>
                    Ride with us.
                </Text>
                <Text fontSize={20} color={"white"} fontWeight={"500"}>
                    Earn Points.
                </Text>
                <Text fontWeight={"500"} color={"white"}>
                    Get Started {"->"}
                </Text>
            </YStack>
            <CarIcon width={187} height={118} />
        </XStack>
    );
}

function ProductUi() {
    return (
        <YStack gap={"$2"}>
            <XStack alignItems={"flex-end"} justifyContent={"space-between"}>
                <H5 color={"black"} fontWeight={"500"}>
                    Our Products
                </H5>
                <H3 color={"#838282"} fontSize={20}>
                    See all
                </H3>
            </XStack>
            <XStack marginBottom={"$4"}>
                {myProducts.map((item) => (
                    <YStack
                        key={item.name}
                        justifyContent="space-between"
                        alignItems="center"
                        flex={1}>
                        <YStack alignItems="center">
                            <YStack
                                backgroundColor="#ECECEC"
                                borderRadius={"$4"}
                                padding={"$4"}
                                marginVertical={"$2"}>
                                {item.icon}
                            </YStack>
                            <Text fontSize={14} color={"#0F0F0F"}>
                                {item.name}
                            </Text>
                        </YStack>
                    </YStack>
                ))}
            </XStack>
        </YStack>
    );
}

function TripUi() {
    return (
        <YStack gap={"$2"}>
            <XStack alignItems={"flex-end"} justifyContent={"space-between"}>
                <H5 color={"black"} fontWeight={"500"}>
                    Your trips
                </H5>
                <H3 color={"#838282"} fontSize={20}>
                    See all
                </H3>
            </XStack>
            <XStack justifyContent={"space-between"} alignItems={"center"}>
                <XStack gap={"$2"} alignItems={"center"}>
                    <SmallFork width={34} height={34} />
                    <YStack gap={"$2"}>
                        <H6 color={"#000"} fontWeight={"500"}>
                            So Fresh
                        </H6>
                        <XStack gap={"$4"} alignItems={"center"}>
                            <XStack gap={"$2"}>
                                <ClockIcon width={16} height={16} />
                                <Text color={"#838282"}>1hr drive</Text>
                            </XStack>
                            <XStack gap={"$2"}>
                                <StarIcon width={16} height={16} />
                                <Text color={"#838282"}>4</Text>
                            </XStack>
                        </XStack>
                    </YStack>
                </XStack>
                <H6 color={"#000"} fontWeight={"500"}>
                    ₦12,000.00
                </H6>
            </XStack>
            <XStack
                justifyContent={"space-between"}
                alignItems={"center"}
                marginTop={"$4"}>
                <XStack gap={"$2"} alignItems={"center"}>
                    <Ridesicon width={34} height={34} />
                    <YStack gap={"$2"}>
                        <H6 color={"#000"} fontWeight={"500"}>
                            Film house cinema
                        </H6>
                        <XStack gap={"$4"} alignItems={"center"}>
                            <XStack gap={"$2"}>
                                <ClockIcon width={16} height={16} />
                                <Text color={"#838282"}>15mins drive</Text>
                            </XStack>
                            <XStack gap={"$2"}>
                                <StarIcon width={16} height={16} />
                                <Text color={"#838282"}>2.5</Text>
                            </XStack>
                        </XStack>
                    </YStack>
                </XStack>
                <H6 color={"#000"} fontWeight={"500"}>
                    ₦5,000.00
                </H6>
            </XStack>
            <XStack
                justifyContent={"space-between"}
                alignItems={"center"}
                marginTop={"$4"}>
                <XStack gap={"$2"} alignItems={"center"}>
                    <Ridesicon width={34} height={34} />
                    <YStack gap={"$2"}>
                        <H6 color={"#000"} fontWeight={"500"}>
                            iFitness Gym
                        </H6>
                        <XStack gap={"$4"} alignItems={"center"}>
                            <XStack gap={"$2"}>
                                <ClockIcon width={16} height={16} />
                                <Text color={"#838282"}>10min drive</Text>
                            </XStack>
                            <XStack gap={"$2"}>
                                <StarIcon width={16} height={16} />
                                <Text color={"#838282"}>2.5</Text>
                            </XStack>
                        </XStack>
                    </YStack>
                </XStack>
                <H6 color={"#000"} fontWeight={"500"}>
                    ₦3,000.00
                </H6>
            </XStack>
        </YStack>
    );
}

function HomeScreen() {
    return (
        <YStack paddingHorizontal={"$4"}>
            <HeaderUI />
            <SearchUI />
            <NearbyUi />
            <BannerUi />
            <ProductUi />
            <TripUi />
        </YStack>
    );
}

A common use case for Server Driven Rendering is managing promotional content. For example, if our BannerUi represents promotional content that needs to be hidden, you simply need to delete or comment it out on the server. This change will automatically remove the promotional content from the React Native application.

Deploying the Server to Production

To deploy the Rise server, we will use Render for hosting.

Create new Web service

Dynamic React Native App Updates from Server

Update the modelSource.ts file in the React Native application to use the new render service link.



export const modelSource = createWSModelSource(
    "https://my-render-link.com/:3015"
);

With any update to the main branch of the server, the server will automatically redeploy. This will trigger an automatic update of the React Native app as well.

Building and Testing the Mobile App for Production

To build and run the iOS app on your physical device in release configuration:
npx expo run:ios --configuration Release --device
This command compiles the app with optimizations enabled and deploys it to your connected iOS device.

To create a release variant of your Android application:
npx expo run:android --variant release
This command generates an optimized APK or App Bundle suitable for distribution and installation

Update your server and monitor the deployment process on Render. Once the deployment is complete, the app will update accordingly.

Component Driven Development with Storybook React Native

Farouq Seriki — Fri, 23 Aug 2024 09:26:18 +0000

🚀 Introduction

Welcome to this comprehensive, beginner-friendly guide on component-driven development using Storybook UI in React Native. This tutorial leverages the power of Expo, Tailwind and Storybook to provide a robust learning experience. GitHub Repo: https://github.com/FastheDeveloper/RN_ComponentDrivenDevelopment_Storybook

🎯 What You'll Learn

Core principles of component-driven development
Harnessing Storybook UI to enhance your development workflow
Bootstrapping a React Native project with Tailwind
Seamlessly integrating Storybook UI into your Expo project
Crafting and showcasing reusable components
Industry best practices for component-driven development

🛠 Prerequisites

Before diving in, make sure you have:

A basic understanding of JavaScript, Typescript and React Native
Node.js and npm installed on your development machine
Make sure you have completed the React Native - Environment Setup instructions
Your preferred code editor ready to go

📚 Tutorial Sections

Introduction to Component-Driven Development
Setting Up Your Expo Project
Integrating Storybook UI
Creating Your First Component
- Crafting a Dynamic Button Component
- Creating a Default Button Story
- Creating Various Button Stories
- Writing Jest Tests for the Button Component
Creating a Dynamic TextInput Component
- Crafting a TextInput with Tailwind CSS
- Creating a Default TextInput Story
- Creating Various TextInput Stories
- Writing Jest Tests for the TextInput Component
Testing Your Components
More Component Examples
Implementing the TextInput and Button Component

Introduction to Component-Driven Development in React Native

Component-Driven Development (CDD) is an approach to building user interfaces that emphasizes creating applications from the "bottom up" using reusable components. This methodology is particularly well-suited for React Native development, given the framework's component-based architecture.

What is Component-Driven Development?

CDD is a development methodology that focuses on building user interfaces by breaking them down into smaller, reusable components. These components are developed in isolation before being assembled into larger features and, ultimately, complete pages or screens.

Key principles of CDD include:

Modularity: Building UIs from discrete, reusable components.
Isolation: Developing and testing components independently.
Composition: Combining smaller components to create larger ones.
Reusability: Designing components for use across different parts of an application.

Benefits for React Native Developers

Adopting CDD in React Native development offers several advantages:

Improved Maintainability: Smaller, self-contained components are easier to understand, update, and debug.
Enhanced Reusability: Well-designed components can be reused across different parts of your app or even in different projects.
Easier Collaboration: Teams can work on different components simultaneously without conflicts.
Consistent Design: Using a library of standard components ensures UI consistency throughout the app.
Efficient Testing: Components can be tested in isolation, making it easier to write and maintain unit tests.

Implementing CDD in React Native

To implement CDD in your React Native project:

Start Small: Begin by identifying and building the smallest, most basic UI elements (buttons, inputs, etc.).
Build a Component Library: Create a collection of reusable components that can be shared across your application.
Use Tools: Leverage tools like Storybook to develop and showcase your components in isolation.
Document Components: Provide clear documentation for each component, including its props, usage examples, and any limitations.
Test Components: Write unit tests for each component to ensure they function correctly in isolation.

By adopting CDD, React Native developers can create more maintainable, scalable, and consistent mobile applications. This approach aligns well with React Native's philosophy and can significantly improve development efficiency and code quality.

Getting Started

Using My Repository

To quickly get started with the pre-configured environment, follow these steps:

Clone the repository using:

 git clone https://github.com/FastheDeveloper/RN_ComponentDrivenDevelopment_Storybook.git

Navigate to the project directory and install the dependencies by running:
```
    yarn

# or

    npm install
```

Setting Up from Scratch

Creating your expo react native application:
```
    npx create-expo-stack@latest
```
Running the above command will create a boilerplate application after asking a few configuration questions.
Setup Storybook In The Project:
```
    npx storybook@latest init
```
This will add a new folder (.storybook) in your project directory
Additional Configuration:
Create an app.config.js File
This configuration facilitates easy switching between Storybook UI for testing and the actual React Native application.
This file defines the storybookEnabled constant based on the environment variable STORYBOOK_ENABLED. This helps determine whether to render Storybook or the main application.
```
export default ({ config }) => ({
    ...config,
    name: 'My_App_Name',  
    slug: 'My_App_Name', 
    extra: {
        storybookEnabled: process.env.STORYBOOK_ENABLED,
    },
});
```

Update package.json File
In the package.json file, add these Storybook scripts. We use these to pass that environment variable to our application, which swaps the entry point to the Storybook UI using cross-env to make sure this works on all platforms (Windows/macOS/Linux).

```
{
    "scripts": {
        "storybook": "cross-env STORYBOOK_ENABLED='true' expo start",
        "storybook:ios": "cross-env STORYBOOK_ENABLED='true' expo ios",
        "storybook:android": "cross-env STORYBOOK_ENABLED='true' expo android"
    }
}
```

4.Setup Entry point (/app/index.tsx) with the env variable:

```javascript
import React from 'react'
import { StyleSheet, Text, View } from 'react-native'
import Constants from 'expo-constants'


function Page() {
return (
    <View style={styles.container}>
    <View style={styles.main}>
        <Text className="text-white">This is the first page of your app.</Text>
    </View>
    </View>
)
}

let AppEntryPoint = Page  

if (Constants?.expoConfig?.extra?.storybookEnabled === 'true') {
const StorybookUI = require('../.storybook').default
AppEntryPoint = () => {
    return (
    <View style={{ flex: 1 }}>
        <StorybookUI />
    </View>
    )
}
}

export default AppEntryPoint

```

5.Run the App for Testing:

To test the app, you can use one of the following commands depending on your target platform:

```shell 
    # Run on iOS
    yarn ios

# or 

    # Run on Android
    yarn android
```

6.Run Storybook to test :

```shell 
    # Run on iOS
    yarn storybook:ios

# or 

    # Run on Android
    yarn storybook:android
```

Creating a Dynamic Button Component

Create Button with StyleSheet/Tailwind css, adding Jest testID to the pressable

        import { ActivityIndicator, Pressable, StyleSheet, Text, View } from 'react-native'
        import React, { ComponentProps } from 'react'
        import { APP_COLOR } from '@constants/colorConstants'
        import { FontAwesome } from '@expo/vector-icons'

        type buttonProps = {
        loading?: boolean
        rightIcon?: keyof typeof FontAwesome.glyphMap
        leftIcon?: keyof typeof FontAwesome.glyphMap
        label: string
        } & ComponentProps<typeof Pressable>

        const AppButton = ({  loading, leftIcon, label, rightIcon, ...pressableProps }: buttonProps) => {
        const content = loading ? (
            <>
            <View

            // style={styles.loaderWrapper}
             className="justify-center h-6"
             >
                <ActivityIndicator size="small" color={'white'} animating={true} />
            </View>
            </>
        ) : (
            <>
            {leftIcon && (
                <View 
                //style={styles.leftIcon}
                className="absolute left-5"
                >
                <FontAwesome name={leftIcon} size={20} />
                </View>
            )}
            <Text 
            className="text-APP_COLOR-MAIN_WHITE text-center text-lg font-bold "
            //style={styles.buttonText}
            >
                {label}
            </Text>
            {rightIcon && (
                <View 
               // style={styles.rightIcon}
                className="absolute right-5"
                >
                <FontAwesome name={rightIcon} size={20} />
                </View>
            )}
            </>
        )
        return (
            <Pressable
            //style={styles.button}
            className="w-full flex justify-center  item-center bg-APP_COLOR-MAIN_GREEN rounded-3xl p-4 shadow-lg"
            {...pressableProps}
            testID="testClick"
            >
            {content}
            </Pressable>
        )
        }

        export default AppButton

        const styles = StyleSheet.create({
            button: {
                alignItems: 'center',
                backgroundColor: APP_COLOR.MAIN_GREEN,
                borderRadius: 24,
                elevation: 5,
                flexDirection: 'row',
                justifyContent: 'center',
                padding: 16,
                width: '100%',
                shadowColor: '#000',
                shadowOffset: {
                height: 2,
                width: 0,
                },
                shadowOpacity: 0.25,
                shadowRadius: 3.84,
            },
            buttonText: {
                color: APP_COLOR.MAIN_WHITE,
                fontSize: 18,
                fontWeight: '700',
                textAlign: 'center',
            },
            loaderWrapper: {
                height: 24,
                justifyContent: 'center',
            },
            rightIcon: {
                position: 'absolute',
                right: 20,
            },
            leftIcon: {
                position: 'absolute',
                left: 20,
            },
        })

Creating Default Button Story

In our story files, we use a syntax called Component Story Format (CSF). In this case, we are using CSF3, which is a newer, updated version of CSF supported by the latest versions of Storybook. This version of CSF has significantly less boilerplate, making it easier to get started.
In Storybook, there are two basic levels of organization: the component and its child stories. Each story can be thought of as a permutation of a component. You can have as many stories per component as needed.

    * Component
        * Story
        * Story
        * Story

To introduce the component we are documenting, we create a default export that contains:

component - the component itself
title - how to refer to the component in the Storybook app's sidebar

argTypes - allows us to specify the types of our args, here we use it to define actions that will log whenever that interaction takes place

    import type { Meta, StoryObj } from '@storybook/react'

    import AppButton from './AppButton'

    import React from 'react'
    import { View } from 'react-native'

    const AppButtonMeta: Meta<typeof AppButton> = {
    title: 'Button',
    component: AppButton,
    argTypes: {
        onPress: { action: 'pressed the button' },
    },
    args: {
        label: 'Story Button',
        loading: false,
    },
    decorators: [
        (Story) => (
        <View style={{ alignItems: 'center', justifyContent: 'center', flex: 1 }}>
            <Story />
        </View>
        ),
    ],
    }

    export default AppButtonMeta

    export const Default: StoryObj<typeof AppButton> = {}

In this example, we create a new default story, which tells Storybook that:

The name in the sidebar should be "Button"
The component it should be attached to is AppButton
The default label should be "Story Button"
The default loading state should be false
The onPress action should run the 'pressed the button' action

Watch Video Here

Creating Various Button Stories

        export const TextOnlyButton: StoryObj<typeof AppButton> = {
        args: {
            label: 'Text Button',
        },
        argTypes: {
            onPress: { action: 'Yaay' },
        },
        parameters: {
            noBackground: true,
        },
        }

        export const WithLeftIcon: StoryObj<typeof AppButton> = {
        args: {
            label: 'With Left Icon',
            leftIcon: 'paper-plane',
        },
        argTypes: {
            onPress: { action: 'Lefty Pressed' },
        },
        parameters: {
            noBackground: true,
        },
        }

        export const WithRightIcon: StoryObj<typeof AppButton> = {
        args: {
            label: 'With Right Icon',
            rightIcon: 'user-circle-o',
        },
        argTypes: {
            onPress: { action: 'Righty Pressed' },
        },
        parameters: {
            noBackground: true,
        },
        }

        export const WithBothIcons: StoryObj<typeof AppButton> = {
        args: {
            label: 'With Both Icons',
            rightIcon: 'user-circle-o',
            leftIcon: 'paper-plane',
        },
        argTypes: {
            onPress: { action: 'Bothy Pressed' },
        },
        parameters: {
            noBackground: true,
        },
        }

Watch Video Here

Creating the Jest Test

    import React from 'react'

    import { render, fireEvent } from '@testing-library/react-native'
    import AppButton from '@/components/Button/AppButton'

    describe('MyButtons', () => {
    it('calls Unpressed when clicked', () => {
        const mockOnPress = jest.fn()
        const { getByTestId } = render(<AppButton label="Test" onPress={mockOnPress} />)
        const pressMeButton = getByTestId('testClick')
        fireEvent.press(pressMeButton)

        expect(mockOnPress).toHaveBeenCalled()
    })
    })

Test Suite Setup:
- We define a test suite named AppButton Component using describe. This groups together related tests for the AppButton component.
Test Case Definition:
- Inside the test suite, there is a single test case defined using the it function. The test case is titled "calls Unpressed when clicked".
Mock Function Creation:
- We create a mock function mockOnPress using jest.fn(). This mock function simulates the onPress prop of the AppButton component to test if it gets called when the button is pressed.
Rendering the Component:
- We render the AppButton component with a label prop set to "Test" and the onPress prop set to mockOnPress using the render function from @testing-library/react-native.
Simulating User Interaction:
- We retrieve the button element using getByTestId with the test ID "testClick". We simulate a press event on the button element using fireEvent.press
Verifying Behavior:
- We assert that the mockOnPress function has been called using expect(mockOnPress).toHaveBeenCalled(). This confirms that the onPress prop function was triggered when the button was pressed.

Running the Jest Test

    yarn test

To execute the test case, use the above command:

Creating a Dynamic TextInput Component

Create Textinput with Tailwind css, adding Jest testID

        import { Pressable, Text, TextInput, View } from 'react-native'
        import React, { ComponentProps, useState } from 'react'
        import { FontAwesome } from '@expo/vector-icons'

        type buttonProps = {
        rightIcon?: keyof typeof FontAwesome.glyphMap
        leftIcon?: keyof typeof FontAwesome.glyphMap
        label?: string
        } & ComponentProps<typeof TextInput>

        const InputField = ({ leftIcon, label, rightIcon, ...inputProps }: buttonProps) => {
        const [hide, setHide] = useState(true)
        return (
            <View className="mx-2">
            <Text className="text-lg font-bold mb-2">{label}</Text>

            <View className="flex-row justify-between items-center bg-APP_COLOR-MAIN_WHITE w-full  mt-2 rounded-xl shadow-xl border border-APP_COLOR-MAIN_GREY ">
                {leftIcon && (
                <View className="ml-2" testID="left-icon">
                    <FontAwesome name={leftIcon} size={20} />
                </View>
                )}

                <TextInput
                className={`h-[52px] w-[85%] px-[2%]  `}
                {...inputProps}
                secureTextEntry={inputProps.secureTextEntry && !rightIcon ? hide : undefined}
                testID="text-input"
                />

                {(rightIcon || inputProps.secureTextEntry) && (
                <View className="mr-2" testID="right-icon">
                    <Pressable onPress={() => (rightIcon ? null : setHide(!hide))} testID="passwordTest">
                    <FontAwesome
                        name={rightIcon || (inputProps.secureTextEntry && (hide ? 'eye' : 'eye-slash')) || undefined}
                        size={20}
                    />
                    </Pressable>
                </View>
                )}
            </View>
            </View>
        )
        }

        export default InputField

Creating Default TextInput Story

        import type { Meta, StoryObj } from '@storybook/react'

        import React from 'react'
        import { View } from 'react-native'
        import InputField from './InputField'

        const InputFieldMeta: Meta<typeof InputField> = {
        title: 'Input Field',
        component: InputField,
        argTypes: {},
        args: {
            label: 'Story Input',
        },
        decorators: [
            (Story) => (
            <View style={{ justifyContent: 'center', flex: 1 }}>
                <Story />
            </View>
            ),
        ],
        }

        export default InputFieldMeta

        export const Default: StoryObj<typeof InputField> = {}

In this example, we create a new default story, which tells Storybook that:

The name in the sidebar should be "Input Field"
The component it should be attached to is InputField
The default label should be "Story Input"

Watch Video Here

Creating Various Textinput Stories

        export const PasswordInput: StoryObj<typeof InputField> = {
        args: {
            secureTextEntry: true,
        },
        }

        export const LeftIconInput: StoryObj<typeof InputField> = {
        args: {
            leftIcon: 'user-circle',
        },
        }

        export const RightIconInput: StoryObj<typeof InputField> = {
        args: {
            rightIcon: 'star',
        },
        }

        export const SafetyIconWithSecureEntry: StoryObj<typeof InputField> = {
        args: {
            rightIcon: 'star',
            secureTextEntry: true,
        },
        }

Watch Video Here

Creating the Jest Test

        import React from 'react'
        import { render, fireEvent } from '@testing-library/react-native'
        import InputField from '@/components/InputField/InputField'


        describe('InputField', () => {
        it('renders correctly with label', () => {
            const { getByText } = render(<InputField label="Test Label" />)
            expect(getByText('Test Label')).toBeTruthy()
        })

        it('renders left icon when provided', () => {
            const { getByTestId } = render(<InputField leftIcon="user" />)
            expect(getByTestId('left-icon')).toBeTruthy()
        })

        it('renders right icon when provided', () => {
            const { getByTestId } = render(<InputField rightIcon="lock" />)
            expect(getByTestId('right-icon')).toBeTruthy()
        })

        it('toggles password visibility when secureTextEntry is true', () => {
            const { getByTestId } = render(<InputField secureTextEntry />)
            const passwordToggle = getByTestId('passwordTest')
            const input = getByTestId('text-input')

            expect(input.props.secureTextEntry).toBe(true)
            fireEvent.press(passwordToggle)
            expect(input.props.secureTextEntry).toBe(false)
            fireEvent.press(passwordToggle)
            expect(input.props.secureTextEntry).toBe(true)
        })

        it('passes additional props to TextInput', () => {
            const { getByTestId } = render(<InputField placeholder="Enter text" />)
            const input = getByTestId('text-input')
            expect(input.props.placeholder).toBe('Enter text')
        })
        })

Testing

This component is tested using Jest and React Native Testing Library. The tests cover various aspects of the InputField component's functionality:

Rendering with label:
Ensures that the component correctly renders the provided label text.
Left icon rendering:
Verifies that the left icon is displayed when the leftIcon prop is provided.
Right icon rendering:
Checks if the right icon is shown when the rightIcon prop is given.
Password visibility toggle:
Tests the functionality of toggling password visibility when secureTextEntry is true. It verifies that:
- The input is initially secure (password hidden)
- Pressing the toggle button makes the input visible
- Pressing the toggle button again makes the input secure
Prop passing:
Confirms that additional props (like placeholder) are correctly passed to the TextInput component.

The tests use render from React Native Testing Library to render the component, and fireEvent to simulate user interactions. getByText and getByTestId are used to query elements in the rendered component.

Running the Jest Test

    yarn test

To execute the test case, use the above command:

Component Examples

For a more comprehensive understanding of how to use this component and to explore additional implementations, please refer to the component folder in the project directory. This folder contains various examples that demonstrate different use cases and configurations Components and Storybook React Native

These examples can serve as practical references,

By examining these examples, you'll gain insights into creating various components using Storybook react native

Building a Basic Sign-Up Screen with Our Components

            import { Text, View } from 'react-native'
            import React, { useState } from 'react'
            import InputField from '@/components/InputField/InputField'
            import AppButton from '@/components/Button/AppButton'
            import { validateEmail, passwordsMatch, allFieldsFilled } from '../utils/Validators'

            export interface UserDetails {
            name: string
            email: string
            password: string
            confirmPassword: string
            }

            const initialUserDetails: UserDetails = {
            name: '',
            email: '',
            password: '',
            confirmPassword: '',
            }

            const SignupScreen = () => {
            const [userDetails, setUserDetails] = useState<UserDetails>(initialUserDetails)

            const handleChange = (name: keyof UserDetails, value: string) => {
                setUserDetails((prevDetails) => ({
                ...prevDetails,
                [name]: value,
                }))
            }

            const isFormValid = () => {
                return (
                validateEmail(userDetails.email) &&
                passwordsMatch(userDetails.password, userDetails.confirmPassword) &&
                allFieldsFilled(userDetails)
                )
            }
            return (
                <View className=" flex-1 mx-4">
                <View className=" items-center  ">
                    <Text className="text-lg text-[#212529] font-bold text-2xl">Let's Gets Signed Up</Text>
                    <Text className="text-[#A3AAB0]"> Create a new account</Text>
                </View>
                <View>
                    <InputField
                    leftIcon="user-o"
                    placeholder="Enter your name"
                    onChangeText={(text) => handleChange('name', text)}
                    />
                    <InputField
                    leftIcon="envelope-o"
                    placeholder="Enter your email"
                    rightIcon={validateEmail(userDetails.email) ? 'check' : undefined}
                    onChangeText={(text) => handleChange('email', text)}
                    />

                    <InputField
                    leftIcon="lock"
                    placeholder="Enter your Password"
                    secureTextEntry
                    onChangeText={(text) => handleChange('password', text)}
                    />
                    <InputField
                    leftIcon="lock"
                    placeholder="Re-Enter your Password"
                    secureTextEntry
                    onChangeText={(text) => handleChange('confirmPassword', text)}
                    />
                </View>
                <View className="flex-1 justify-end mx-2">
                    <AppButton label="Sign Up" disabled={!isFormValid()} />
                </View>
                </View>
            )
            }

            export default SignupScreen

This basic usage demonstrates how component-driven development with Storybook enhances the reusability of components that are created in isolation and tested with Jest. It provides confidence in their performance and functionality, showcasing the benefits of using Storybook for building and validating components.

Watch Video Here

Happy coding! 🎉🎉🎉

DEV Community: Farouq Seriki

OWASP Mobile Top 10 for React Native Fintech Apps: A Practical Implementation Checklist

TL;DR

Why This Matters Now

Project Setup

M1: Improper Credential Usage

In the Demo App

Checklist

M2: Inadequate Supply Chain Security

Checklist

M3: Insecure Authentication and Authorization

In the Demo App

Checklist

M4: Insufficient Input/Output Validation

In the Demo App

Checklist

M5: Insecure Communication

In the Demo App

Checklist

M6: Inadequate Privacy Controls

In the Demo App

04-screenshot-demo.mp4 - Google Drive

Checklist

M7: Insufficient Binary Protections

Checklist

M8: Security Misconfiguration

In the Demo App

Checklist

M9: Insecure Data Storage

Checklist

M10: Insufficient Cryptography

In the Demo App

Checklist

The Full Checklist

What a Security Audit Actually Looks For

Conclusion

WatermelonDB + Expo SDK 54: The Complete Mobile Offline-First Setup Guide That Actually Works 🍉

🛠️ Prerequisites

🧵 The Pattern That Got Me Here

🧱 Where the Queue Pattern Hits Its Ceiling

⚔️ The Landscape: WatermelonDB vs PowerSync vs ElectricSQL

🍉 WatermelonDB — Full Control, Full Responsibility

⚡ PowerSync — Sync as a Service

🌿 ElectricSQL + TanStack DB — The Open-Source Middle Ground

📊 The Comparison Table

🏅 Honorable Mentions

🤔 Why I Chose WatermelonDB (and When I Would Choose Differently)

🔧 The Setup That Actually Works: WatermelonDB + Expo SDK 54

📦 Installation — The Exact Commands

🩹 Fixing the React 19 Peer Dependency

🔌 The Expo Config Plugin

🗂️ Schema Definition

🏗️ Model Classes

🚀 Database Initialization

🐛 The window.performance.now.bind Crash

📋 Schema Migrations

⚙️ EAS Build Configuration

🍎 iOS-Specific: The simdjson Duplicate Dependency

Apple Silicon Simulator Build Failure 🖥️

🔷 TypeScript Configuration

🔄 Sync Implementation — The Full-Stack View

🧠 The Sync Protocol (Mental Model)

🖥️ Expo API Routes — The Demo Backend

🪝 Client Sync Hook

🌐 Auto-Sync on Reconnect

🏭 Production Backend: NestJS + PostgreSQL

⚡ Conflict Resolution in Practice

🛡️ Production Hardening

Schema Migrations Between App Versions

☢️ Database Reset Strategy

⚡ Performance Tips

🐞 Troubleshooting — The Errors You Will Actually Hit

❌ window.performance.now.bind is not a function

❌ simdjson duplicate dependency in Podfile

❌ simdjson build failure on Apple Silicon simulators

❌ @nozbe/with-observables React 19 peer dependency warning

❌ JSI not loading on Android

❌ EAS Update OTA push does not include schema changes

🔀 Migration Path: From MMKV Queues to WatermelonDB

🥊 Pick Your Fighter: The Decision Tree

🐛 The `window.performance.now.bind` Crash

🍎 iOS-Specific: The `simdjson` Duplicate Dependency

❌ `window.performance.now.bind is not a function`

❌ `simdjson` duplicate dependency in Podfile

❌ `simdjson` build failure on Apple Silicon simulators

❌ `@nozbe/with-observables` React 19 peer dependency warning

⚠️ `react-native-fs` Version Compatibility

`Android`

`ios`

`Android`

`ios`

Setting Up `server.ts`