React Native / Expo × Swift Native Modules: Choosing Between the Expo Modules API and Turbo Native Modules, with Production Code

Error: FunctionCallException: Calling the 'setTheme' function has failed
→ Caused by: ArgumentCastException: Argument at index '0' couldn't be cast to type Enum<Theme>
→ Caused by: EnumNoSuchValueException: 'not-a-real-theme' is not present in Theme enum, it must be one of: 'light', 'dark', 'system'

npx create-expo-module@latest --local   # creates modules/<name>/
npx expo prebuild --clean               # regenerates the native project and autolinks the module
npx expo run:ios                        # your own native code doesn't run in Expo Go — verify in a development build

modules/text-recognition/
├── expo-module.config.json   # which Swift classes are registered as modules
├── index.ts                  # the public API the app imports (the wrapper)
├── src/
│   └── TextRecognitionModule.ts  # only requireNativeModule and type declarations
└── ios/
    ├── MyAppTextRecognition.podspec  # ← without this, the module is silently not linked (see below)
    └── TextRecognitionModule.swift

{
  "platforms": ["apple", "android"],
  "apple": { "modules": ["TextRecognitionModule"] },
  "android": { "modules": ["expo.modules.textrecognition.TextRecognitionModule"] }
}

// ❌ "Not linked" looks exactly the same as "unsupported device"
try {
  return requireNativeModule('DeviceCheck');
} catch {
  return null; // meant to treat it like the simulator or Android
}

# ios/MyAppTextRecognition.podspec
Pod::Spec.new do |s|
  s.name           = 'MyAppTextRecognition'   # name it 'Vision' and import Vision points at itself
  s.version        = '1.0.0'
  s.summary        = 'On-device text recognition (Vision).'
  s.author         = ''
  s.homepage       = 'https://docs.expo.dev/modules/'
  s.platforms      = { :ios => '16.4' }       # the SDK 57 template's value — match your app's minimum OS
  s.source         = { git: '' }
  s.static_framework = true
  s.dependency 'ExpoModulesCore'
  s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
end

// modules/text-recognition/ios/TextRecognitionModule.swift
import ExpoModulesCore
import UIKit
import Vision

/// Options passed from JS. Fields omitted on the JS side get their defaults
struct ReadPageOptions: Record {
  @Field var level: RecognitionLevel = .accurate
  @Field var languages: [String] = ["ja-JP", "en-US"]
  /// OFF by default. See 3-2 for why
  @Field var usesLanguageCorrection: Bool = false
}

enum RecognitionLevel: String, Enumerable {
  case fast
  case accurate

  var vision: VNRequestTextRecognitionLevel { self == .fast ? .fast : .accurate }
}

/// Making the return value a Record too keeps it one-to-one with the JS types
struct RecognizedCharacter: Record {
  @Field var text: String = ""
  @Field var xmin: Int = 0
  @Field var ymin: Int = 0
  @Field var xmax: Int = 0
  @Field var ymax: Int = 0
}

struct RecognizedLine: Record {
  @Field var characters: [RecognizedCharacter] = []
}

public final class TextRecognitionModule: Module {
  /// Vision is heavy. Run it on a dedicated serial queue so it doesn't block the shared default queue
  private static let queue = DispatchQueue(label: "app.text-recognition", qos: .userInitiated)

  public func definition() -> ModuleDefinition {
    Name("TextRecognition")

    // A capability check can be synchronous. Callers use it to decide whether to try at all
    Function("supportedLanguages") { (level: RecognitionLevel) -> [String] in
      Self.supportedLanguages(level: level)
    }

    AsyncFunction("readPage") { (url: URL, options: ReadPageOptions) throws -> [RecognizedLine] in
      // Trust boundary: local files only. A module that fetches arbitrary URLs becomes a request-forgery tool
      guard url.isFileURL else { throw NotAFileURLException() }
      guard let image = UIImage(contentsOfFile: url.path), let cgImage = image.cgImage else {
        throw ImageUnreadableException()
      }

      // Available languages differ by OS. Ask what actually works instead of hard-coding versions
      let available = Set(Self.supportedLanguages(level: options.level))
      let languages = options.languages.filter(available.contains)
      guard !languages.isEmpty else { throw LanguageUnavailableException(options.languages) }

      let request = VNRecognizeTextRequest()
      request.recognitionLevel = options.level.vision
      request.usesLanguageCorrection = options.usesLanguageCorrection
      request.recognitionLanguages = languages

      let handler = VNImageRequestHandler(
        cgImage: cgImage,
        orientation: CGImagePropertyOrientation(image.imageOrientation)
      )
      do {
        try handler.perform([request])
      } catch {
        throw RecognitionFailedException().causedBy(error)
      }

      return (request.results ?? []).compactMap { observation in
        guard let candidate = observation.topCandidates(1).first else { return nil }
        let line = RecognizedLine()
        line.characters = PageGeometry.characters(of: candidate)
        return line
      }
    }
    .runOnQueue(Self.queue)
  }

  private static func supportedLanguages(level: RecognitionLevel) -> [String] {
    let request = VNRecognizeTextRequest()
    request.recognitionLevel = level.vision
    return (try? request.supportedRecognitionLanguages()) ?? []
  }
}

// modules/text-recognition/ios/PageGeometry.swift
import UIKit
import Vision

/// Converts Vision's normalised coordinates (origin bottom-left, 0...1) to the app's (origin top-left, 0...1000)
enum PageGeometry {
  static let space: CGFloat = 1000

  static func characters(of candidate: VNRecognizedText) -> [RecognizedCharacter] {
    let string = candidate.string
    return string.indices.compactMap { index in
      let range = index..<string.index(after: index)
      guard let rect = try? candidate.boundingBox(for: range)?.boundingBox,
            let box = box(from: rect) else { return nil }
      // @Field is a reference-type (final class) wrapper, so values can be set through a let
      let character = RecognizedCharacter()
      character.text = String(string[range])
      (character.xmin, character.ymin, character.xmax, character.ymax) = box
      return character
    }
  }

  /// nil for anything that isn't a real box. Never fill in a guess
  static func box(from rect: CGRect) -> (Int, Int, Int, Int)? {
    // Int(_:) traps (crashes) on a non-finite value. Don't trust values that come from a photo
    guard rect.minX.isFinite, rect.maxX.isFinite, rect.minY.isFinite, rect.maxY.isFinite,
          rect.width > 0, rect.height > 0 else { return nil }
    // The Y-axis flip happens here and nowhere else. Flip twice and an upside-down box still passes range checks
    return (
      coordinate(rect.minX, .down), coordinate(1 - rect.maxY, .down),
      coordinate(rect.maxX, .up), coordinate(1 - rect.minY, .up)
    )
  }

  /// Always round outward. Rounding inward leaves the edge of a hidden character showing
  static func coordinate(_ value: CGFloat, _ rule: FloatingPointRoundingRule) -> Int {
    Int(min(max((value * space).rounded(rule), 0), space))
  }
}

extension CGImagePropertyOrientation {
  /// Map name to name. The two enums number the same cases differently (.right is 3 in one, 6 in the other)
  init(_ orientation: UIImage.Orientation) {
    switch orientation {
    case .up: self = .up
    case .upMirrored: self = .upMirrored
    case .down: self = .down
    case .downMirrored: self = .downMirrored
    case .left: self = .left
    case .leftMirrored: self = .leftMirrored
    case .right: self = .right
    case .rightMirrored: self = .rightMirrored
    @unknown default: self = .up
    }
  }
}

// modules/text-recognition/ios/TextRecognitionExceptions.swift
import ExpoModulesCore

// Unless overridden, code is derived from the class name.
// Names containing acronyms come out mangled: NotAFileURLException → "ERR_NOT_AFILE_UR_L" (computed with the SDK 57 rule).
// Override the codes JS branches on, so renaming the class can't break the contract
final class NotAFileURLException: Exception, @unchecked Sendable {
  override var code: String { "ERR_TEXT_RECOGNITION_NOT_A_FILE_URL" }
  override var reason: String { "Only local file URLs are accepted." }
}

final class ImageUnreadableException: Exception, @unchecked Sendable {
  override var reason: String { "The image could not be opened." }
}

final class LanguageUnavailableException: GenericException<[String]>, @unchecked Sendable {
  override var code: String { "ERR_TEXT_RECOGNITION_LANGUAGE_UNAVAILABLE" }
  override var reason: String { "None of the requested languages is available on this OS: \(param)" }
}

final class RecognitionFailedException: Exception, @unchecked Sendable {
  override var reason: String { "Text recognition failed for this image." }
}

// modules/text-recognition/src/TextRecognitionModule.ts
import { NativeModule, requireOptionalNativeModule } from 'expo';

export type RecognitionLevel = 'fast' | 'accurate';

export interface ReadPageOptions {
  readonly level?: RecognitionLevel;
  readonly languages?: readonly string[];
  readonly usesLanguageCorrection?: boolean;
}

export interface RecognizedCharacter {
  readonly text: string;
  readonly xmin: number;
  readonly ymin: number;
  readonly xmax: number;
  readonly ymax: number;
}

export interface RecognizedLine {
  readonly characters: readonly RecognizedCharacter[];
}

declare class TextRecognitionNativeModule extends NativeModule {
  supportedLanguages(level: RecognitionLevel): string[];
  readPage(uri: string, options: ReadPageOptions): Promise<RecognizedLine[]>;
}

/** null when not found (Android not implemented, web, not linked). Never throws */
export default requireOptionalNativeModule<TextRecognitionNativeModule>('TextRecognition');

// modules/text-recognition/index.ts
import TextRecognition, { type ReadPageOptions, type RecognizedLine } from './src/TextRecognitionModule';

export type { ReadPageOptions, RecognizedCharacter, RecognizedLine } from './src/TextRecognitionModule';

/** The code Swift's LanguageUnavailableException overrides. Its spelling is pinned by a contract test */
export const LANGUAGE_UNAVAILABLE = 'ERR_TEXT_RECOGNITION_LANGUAGE_UNAVAILABLE';

export type ReadPageResult =
  | { readonly status: 'read'; readonly lines: readonly RecognizedLine[]; readonly text: string }
  | { readonly status: 'unavailable'; readonly reason: 'module-missing' | 'language-missing' }
  | { readonly status: 'failed'; readonly code: string };

function errorCode(error: unknown): string {
  return typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
    ? error.code
    : 'ERR_UNKNOWN';
}

export async function readPage(uri: string, options: ReadPageOptions = {}): Promise<ReadPageResult> {
  if (TextRecognition === null) return { status: 'unavailable', reason: 'module-missing' };
  try {
    const lines = await TextRecognition.readPage(uri, options);
    // Build the text from characters that have boxes, so the string you match and the boxes you mask never disagree
    const text = lines.map((line) => line.characters.map((c) => c.text).join('')).join('\n');
    return { status: 'read', lines, text };
  } catch (error) {
    const code = errorCode(error);
    return code === LANGUAGE_UNAVAILABLE
      ? { status: 'unavailable', reason: 'language-missing' }
      : { status: 'failed', code };
  }
}

// modules/app-attest/ios/AppAttestModule.swift
import CryptoKit
import DeviceCheck
import ExpoModulesCore

public final class AppAttestModule: Module {
  public func definition() -> ModuleDefinition {
    Name("AppAttest")

    // Always false on the simulator
    Function("isSupported") { () -> Bool in
      DCAppAttestService.shared.isSupported
    }

    // Only the key ID goes back to JS. The private key never leaves the Secure Enclave; no API can export it
    AsyncFunction("generateKey") { () async throws -> String in
      guard DCAppAttestService.shared.isSupported else { throw AppAttestUnsupportedException() }
      return try await DCAppAttestService.shared.generateKey()
    }

    AsyncFunction("generateAssertion") { (keyId: String, challengeBase64: String) async throws -> String in
      guard let challenge = Data(base64Encoded: challengeBase64) else {
        throw AppAttestInvalidChallengeException()
      }
      do {
        // Hash on the native side, so client and server can never disagree about what was signed
        let assertion = try await DCAppAttestService.shared.generateAssertion(
          keyId, clientDataHash: Data(SHA256.hash(data: challenge))
        )
        return assertion.base64EncodedString()
      } catch let error as DCError where error.code == .invalidKey {
        // Convert only the failure we need to tell apart. Every other DCError stays ERR_UNEXPECTED
        throw AppAttestInvalidKeyException()
      }
    }
  }
}

final class AppAttestUnsupportedException: Exception, @unchecked Sendable {
  override var reason: String { "App Attest is not supported on this device." }
}

final class AppAttestInvalidChallengeException: Exception, @unchecked Sendable {
  override var reason: String { "Challenge was not valid base64." }
}

/// The key ID survives in the Keychain, but the key itself is lost on reinstall or device migration
final class AppAttestInvalidKeyException: Exception, @unchecked Sendable {
  // JS branches on this exact spelling. Pin it instead of deriving it from the class name
  override var code: String { "ERR_APP_ATTEST_INVALID_KEY" }
  override var reason: String { "The App Attest key is no longer held by this device." }
}

export type AssertionResult =
  | { readonly status: 'signed'; readonly assertion: string }
  | { readonly status: 'invalid_key' } // only this one regenerates the key
  | { readonly status: 'failed' };     // transient. Keep using the same key

AsyncFunction("isAppActive") { () async -> Bool in
  await MainActor.run { UIApplication.shared.applicationState == .active }
}

// modules/network-quality/ios/NetworkQualityModule.swift
import ExpoModulesCore
import Network

public final class NetworkQualityModule: Module {
  private var monitor: NWPathMonitor?
  private let queue = DispatchQueue(label: "app.network-quality")

  public func definition() -> ModuleDefinition {
    Name("NetworkQuality")
    Events("onChange")

    // Start monitoring when the first listener is added. No battery spent while nobody listens
    OnStartObserving("onChange") {
      let monitor = NWPathMonitor() // create a fresh one on each start; don't reuse after cancel
      monitor.pathUpdateHandler = { [weak self] path in
        self?.sendEvent("onChange", [
          "isConnected": path.status == .satisfied,
          "isExpensive": path.isExpensive,     // cellular, personal hotspot
          "isConstrained": path.isConstrained, // Low Data Mode
        ])
      }
      monitor.start(queue: queue)
      self.monitor = monitor
    }

    // Stop when the last listener is removed
    OnStopObserving("onChange") {
      monitor?.cancel()
      monitor = nil
    }

    OnDestroy {
      monitor?.cancel()
    }
  }
}

// modules/network-quality/index.ts
import { EventEmitter, NativeModule, requireOptionalNativeModule, useEvent } from 'expo';

export interface NetworkQuality {
  readonly isConnected: boolean;
  readonly isExpensive: boolean;
  readonly isConstrained: boolean;
}

type Events = { onChange: (quality: NetworkQuality) => void };

declare class NetworkQualityModule extends NativeModule<Events> {}

/**
 * Where the module doesn't exist (Android not implemented, web, not linked), use an emitter that never fires.
 * That way useEvent can always be called, so no hook is called conditionally (rules-of-hooks holds)
 */
const emitter =
  requireOptionalNativeModule<NetworkQualityModule>('NetworkQuality') ?? new EventEmitter<Events>();

/** When nothing is known, assume no constraints. Failing closed would stop sync on Android and web */
const UNKNOWN: NetworkQuality = { isConnected: true, isExpensive: false, isConstrained: false };

export function useNetworkQuality(): NetworkQuality {
  return useEvent(emitter, 'onChange', UNKNOWN);
}

// modules/pdf-pages/ios/PdfPagesModule.swift (SharedObject version)
import ExpoModulesCore
import PDFKit

final class PdfDocumentObject: SharedObject {
  let document: PDFDocument
  let pageCount: Int // kept as an immutable value, so reads from the JS thread can't race

  init(document: PDFDocument) {
    self.document = document
    self.pageCount = document.pageCount
    super.init()
  }
}

public final class PdfPagesModule: Module {
  /// A dedicated serial queue: PDFDocument is never touched from two threads at once, and other modules aren't kept waiting
  private static let renderQueue = DispatchQueue(label: "app.pdf-pages", qos: .userInitiated)

  public func definition() -> ModuleDefinition {
    Name("PdfPages")

    // The file is opened exactly once
    AsyncFunction("openAsync") { (url: URL) throws -> PdfDocumentObject in
      guard url.isFileURL, let document = PDFDocument(url: url) else { throw PdfUnreadableException() }
      return PdfDocumentObject(document: document)
    }
    .runOnQueue(Self.renderQueue)

    Class("PdfDocument", PdfDocumentObject.self) {
      Property("pageCount") { (pdf: PdfDocumentObject) -> Int in pdf.pageCount }

      AsyncFunction("renderPageAsync") { (pdf: PdfDocumentObject, pageIndex: Int, maxWidth: Double) throws -> String in
        // The renderer (PdfPageRenderer) is the original implementation extracted into a function; described below
        try PdfPageRenderer.render(pdf.document, pageIndex: pageIndex, maxWidth: maxWidth)
      }
      .runOnQueue(Self.renderQueue)
    }
  }
}

// modules/pdf-pages/index.ts
import { NativeModule, requireOptionalNativeModule, SharedObject } from 'expo';
import { useEffect, useState } from 'react';

declare class PdfDocument extends SharedObject {
  readonly pageCount: number;
  renderPageAsync(pageIndex: number, maxWidth: number): Promise<string>;
}

declare class PdfPagesModule extends NativeModule {
  openAsync(uri: string): Promise<PdfDocument>;
}

const PdfPages = requireOptionalNativeModule<PdfPagesModule>('PdfPages');

/** Released when uri changes or the screen goes away. Leaving before it finishes opening leaves no native PDF behind */
export function usePdfDocument(uri: string | null): PdfDocument | null {
  const [document, setDocument] = useState<PdfDocument | null>(null);

  useEffect(() => {
    if (uri === null || PdfPages === null) return;
    let disposed = false;
    let opened: PdfDocument | null = null;

    PdfPages.openAsync(uri).then(
      (doc) => {
        if (disposed) {
          doc.release(); // too late to use it — release it the moment it arrives
          return;
        }
        opened = doc;
        setDocument(doc);
      },
      () => setDocument(null),
    );

    return () => {
      disposed = true;
      opened?.release();
      setDocument(null);
    };
  }, [uri]);

  return document;
}

// specs/NativeLocalStorage.ts — file and module names start with "Native" (an official rule)
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  setItem(value: string, key: string): void;
  getItem(key: string): string | null;
  removeItem(key: string): void;
  clear(): void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('NativeLocalStorage');

{
  "codegenConfig": {
    "name": "NativeLocalStorageSpec",
    "type": "modules",
    "jsSrcsDir": "specs",
    "android": { "javaPackageName": "com.nativelocalstorage" },
    "ios": { "modulesProvider": { "NativeLocalStorage": "RCTNativeLocalStorage" } }
  }
}

// NativeLocalStorage.swift — all the real work lives in Swift
@objcMembers public class NativeLocalStorage: NSObject {
  let userDefaults = UserDefaults(suiteName: "local-storage")

  public func getItem(for key: String) -> String? { userDefaults?.string(forKey: key) }
  public func setItem(for key: String, value: String) { userDefaults?.set(value, forKey: key) }
  public func removeItem(for key: String) { userDefaults?.removeObject(forKey: key) }
  public func clear() { userDefaults?.dictionaryRepresentation().keys.forEach { removeItem(for: $0) } }
}

// RCTNativeLocalStorage.mm — conforms to the Codegen protocol and forwards to Swift, nothing more
#import "RCTNativeLocalStorage.h"
#import "SampleApp-Swift.h" // Swift's public header generated by Xcode ("SampleApp" is your app name)

@implementation RCTNativeLocalStorage {
  NativeLocalStorage *storage;
}

- (id)init {
  if (self = [super init]) { storage = [NativeLocalStorage new]; }
  return self;
}

- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params {
  return std::make_shared<facebook::react::NativeLocalStorageSpecJSI>(params);
}

- (NSString *_Nullable)getItem:(NSString *)key { return [storage getItemFor:key]; }
- (void)setItem:(NSString *)value key:(NSString *)key { [storage setItemFor:key value:value]; }
- (void)removeItem:(NSString *)key { [storage removeItemFor:key]; }
- (void)clear { [storage clear]; }

+ (NSString *)moduleName { return @"NativeLocalStorage"; }
@end

// app.config.ts (excerpt)
const APP_GROUP = 'group.com.example.app';

export default (): ExpoConfig => ({
  // ...
  ios: {
    bundleIdentifier: 'com.example.app',
    entitlements: { 'com.apple.security.application-groups': [APP_GROUP] },
    privacyManifests: {
      NSPrivacyAccessedAPITypes: [
        {
          NSPrivacyAccessedAPIType: 'NSPrivacyAccessedAPICategoryUserDefaults',
          // CA92.1: the app's own settings / 1C8F.1: the App Group shared with the widget
          NSPrivacyAccessedAPITypeReasons: ['CA92.1', '1C8F.1'],
        },
      ],
    },
  },
});

// modules/app-lifecycle/ios/AppLifecycleDelegate.swift
import ExpoModulesCore

public class AppLifecycleDelegate: ExpoAppDelegateSubscriber {
  public func applicationDidEnterBackground(_ application: UIApplication) {
    // For example: persist the queue of unsent work
  }
}

{ "apple": { "appDelegateSubscribers": ["AppLifecycleDelegate"] } }

// modules/text-recognition/__tests__/readPage.test.ts
import { readFileSync } from 'node:fs';
import { join } from 'node:path';

const mockReadPage = jest.fn();

jest.mock('../src/TextRecognitionModule', () => ({
  __esModule: true,
  default: { readPage: (...args: unknown[]) => mockReadPage(...args), supportedLanguages: jest.fn() },
}));

// import after jest.mock
import { LANGUAGE_UNAVAILABLE, readPage } from '..';

beforeEach(() => mockReadPage.mockReset());

test('builds the page text from the character boxes', async () => {
  mockReadPage.mockResolvedValue([
    { characters: [{ text: '条', xmin: 0, ymin: 0, xmax: 10, ymax: 10 }] },
  ]);
  await expect(readPage('file:///page.jpg')).resolves.toMatchObject({ status: 'read', text: '条' });
});

test('tells a missing language apart from a failed read', async () => {
  mockReadPage.mockRejectedValueOnce(Object.assign(new Error('x'), { code: LANGUAGE_UNAVAILABLE }));
  await expect(readPage('file:///page.jpg')).resolves.toEqual({
    status: 'unavailable',
    reason: 'language-missing',
  });

  mockReadPage.mockRejectedValueOnce(Object.assign(new Error('x'), { code: 'ERR_UNEXPECTED' }));
  await expect(readPage('file:///page.jpg')).resolves.toEqual({ status: 'failed', code: 'ERR_UNEXPECTED' });
});

test('Swift throws the code with the same spelling as TS (contract test)', () => {
  const swift = readFileSync(join(__dirname, '..', 'ios', 'TextRecognitionExceptions.swift'), 'utf8');
  // If the spelling drifts, every "missing language" silently turns into a "failure" — and nobody notices
  expect(swift).toContain(`"${LANGUAGE_UNAVAILABLE}"`);
});

// src/native-modules-health.ts
import { requireOptionalNativeModule } from 'expo';
import { Platform } from 'react-native';

/** Modules every iOS build must contain. Add new ones here too */
const REQUIRED_ON_IOS = ['TextRecognition', 'AppAttest', 'NetworkQuality', 'PdfPages'] as const;

export function findMissingNativeModules(): string[] {
  if (Platform.OS !== 'ios') return [];
  return REQUIRED_ON_IOS.filter((name) => requireOptionalNativeModule(name) === null);
}