React Native 0.76 JSI vs Flutter Platform Channels: calling a native barcode scanner 1000 times

ialize JSI bridge (called once at app startup, e.g., in App.tsx) export const initBarCodeJsi = (): void => { if (Platform.OS === 'ios') { // iOS JSI injection: access global native object injected via Obj-C++ bridge if ((global as any).barCodeScannerJsi) { jsiScanBarCode = (global as any).barCodeScannerJsi.scan; console.log('JSI BarCode module initialized on iOS'); } else { console.warn('JSI BarCode module not injected on iOS. Falling back to legacy bridge.'); jsiScanBarCode = null; } } else if (Platform.OS === 'android') { // Android JSI injection: access JSI global injected via C++ bridge if ((global as any).BarCodeScannerJsiModule) { jsiScanBarCode = (global as any).BarCodeScannerJsiModule.scan; console.log('JSI BarCode module initialized on Android'); } else { console.warn('JSI BarCode module not injected on Android. Falling back to legacy bridge.'); jsiScanBarCode = null; } } else { throw new Error(Unsupported platform: ${Platform.OS}); } };

// Scan barcode using JSI (falls back to legacy if JSI unavailable) export const scanBarCodeJsi = async (options: { cameraId?: string; scanTimeoutMs?: number; allowedTypes?: BarCodeType[]; } = {}): Promise<{ rawValue: string; type: BarCodeType; timestampMs: number; }> => { // Validate inputs to prevent invalid native calls if (options.scanTimeoutMs && options.scanTimeoutMs < 100) { throw new Error('scanTimeoutMs must be ≥ 100ms to prevent camera timeout'); } if (options.allowedTypes && !Array.isArray(options.allowedTypes)) { throw new Error('allowedTypes must be an array of BarCodeType enums'); }

// Use JSI if available (3-5x faster than legacy bridge) if (jsiScanBarCode) { try { const result = await jsiScanBarCode({ cameraId: options.cameraId || 'default', scanTimeoutMs: options.scanTimeoutMs || 5000, allowedTypes: options.allowedTypes || ['QR_CODE', 'CODE_128'], }); // Validate native response to catch malformed data early if (!result.rawValue || typeof result.rawValue !== 'string') { throw new Error('Invalid native response: missing or invalid rawValue'); } if (!result.type || typeof result.type !== 'string') { throw new Error('Invalid native response: missing or invalid type'); } return result; } catch (err) { console.error('JSI scan failed, falling back to legacy bridge:', err); // Fallback to legacy NativeModules bridge if JSI call fails return NativeModules.BarCodeScannerModule.scan(options); } } else { // Fallback to legacy bridge if JSI not initialized console.log('Using legacy bridge for barcode scan'); return NativeModules.BarCodeScannerModule.scan(options); } };

// Cleanup JSI references (call on app tear down to prevent memory leaks) export const cleanupBarCodeJsi = (): void => { jsiScanBarCode = null; console.log('JSI BarCode module cleaned up'); };

// lib/bar_code_scanner_channel.dart // Flutter Platform Channels implementation for native barcode scanning // Requires Flutter 3.24.3+, iOS 14+/Android 8+, camera plugin 0.10.0+ import 'dart:async'; import 'dart:io'; import 'package:flutter/services.dart';

enum BarCodeType { qrCode, code128, ean13, upcA, dataMatrix }

class BarCodeScanResult { final String rawValue; final BarCodeType type; final int timestampMs; final Map? metadata;

BarCodeScanResult({ required this.rawValue, required this.type, required this.timestampMs, this.metadata, });

factory BarCodeScanResult.fromMap(Map map) { return BarCodeScanResult( rawValue: map['rawValue'] as String, type: BarCodeType.values.firstWhere( (e) => e.name == (map['type'] as String), orElse: () => BarCodeType.qrCode, ), timestampMs: map['timestampMs'] as int, metadata: map['metadata'] as Map?, ); } }

class BarCodeScannerCha

## Pitfall Guide
1. **JSI Injection Timing Misalignment**: JSI globals are populated during native runtime initialization. Invoking `scanBarCodeJsi` before `initBarCodeJsi` completes results in silent fallback or null reference crashes. Always gate JSI calls with explicit initialization checks.
2. **Blocking the JS Thread with Synchronous JSI**: While JSI supports sync calls, blocking the JS thread for >16ms causes frame drops and ANR-like behavior. Wrap heavy native operations in async promises or offload to worker threads.
3. **JSON Serialization Bloat in Platform Channels**: Default MethodChannels serialize all payloads to JSON. For high-frequency small payloads (<1KB), this adds ~0.6ms overhead per call and increases GC pressure. Use binary codecs or custom MethodChannel codecs when throughput is critical.
4. **Missing Fallback Chains**: JSI injection can fail on legacy RN versions, ProGuard/R8 stripping, or misconfigured CMake builds. Without graceful fallback to `NativeModules` or `MethodChannel`, the feature becomes completely unavailable in production.
5. **Uncleaned Native References & Memory Leaks**: Failing to nullify JSI function references or dispose `EventChannel`/`MethodChannel` streams prevents garbage collection. In long-running sessions (e.g., retail checkout), this causes gradual memory bloat and OOM crashes.
6. **Assuming Flutter Throughput Equals UI Responsiveness**: Higher async throughput doesn't prevent event loop congestion. Burst calls still cause micro-stutters without proper throttling, debouncing, or `compute()` offloading for heavy decoding steps.

## Deliverables
- **Bridge Selection Blueprint**: Architecture decision matrix covering latency thresholds, payload sizes, sync requirements, and runtime version constraints. Includes flowcharts for JSI vs MethodChannel adoption paths.
- **Pre-Integration Checklist**: 12-step validation protocol covering Hermes/FFI version verification, native module build flags, JSI injection timing tests, fallback mechanism validation, and thermal throttling simulation.
- **Configuration Templates**: Ready-to-use `react-native.config.js` Hermes flags, Flutter `pubspec.yaml` channel setup, Android `CMakeLists.txt` JSI linking snippets, and iOS `Podfile` post-install hooks for bridge optimization.