React Native Brownfield

React Native Brownfield is a set of helpers designed to facilitate the smooth integration of React Native into existing native applications (brownfield integration). It allows developers to incrementally adopt React Native without rewriting the entire app.

Key capabilities include:

• Single-method startup: Start React Native and invoke code immediately upon loading.
• Architecture Compatibility: Supports both legacy and the new React Native architecture.
• Instance Reuse: Reuse the same React Native instance across different native components.
• Native UI Support: Compatible with UIKit/SwiftUI (iOS) and Fragments/Jetpack Compose (Android).
• Language Support: Works with Objective-C, Swift, Java, and Kotlin.
• Navigation Flexibility: Works with any native navigation pattern or JavaScript-based navigation.
• Gesture Control: Ability to enable/disable native gestures and hardware buttons from JavaScript.
• Automated Build: Includes a CLI to automate the build process.

The apps/ directory contains several demo projects that illustrate how to integrate React Native into existing native applications using different configurations:

React Native Providers (The libraries being integrated)

• RNApp: A standard React Native application packaged into AAR (Android) and XCFramework (iOS) archives for integration into native projects.
• ExpoApp56: An Expo application using Expo SDK v56 (demonstrates Expo Updates).
• ExpoApp57: An Expo application using Expo SDK v57 (uses the default expo consumer alias).
• ExpoAppPreview: A temporary Expo app used for testing new Expo preview releases.

Native Consumers (The host applications)

• AndroidApp: A native Android application that consumes the RN packages. It has two flavors:
  • expo: Consumes the artifact from ExpoApp.
  • vanilla: Consumes the artifact from RNApp.
• AppleApp: A native iOS application that consumes packaged XCFrameworks. It defines specific targets for each provider:
  • Brownfield Apple App (RNApp) (Vanilla)
  • Brownfield Apple App (ExpoApp56)
  • Brownfield Apple App (ExpoApp57)
  • Brownfield Apple App (ExpoAppPreview)

Brownie uses a code generation workflow to ensure type safety across the bridge between TypeScript and native platforms. The workflow follows these steps:

1. Define: Create your store shape in a *.brownie.ts file using TypeScript.
2. Generate: Run the brownfield codegen command via the Brownfield CLI to generate native types.
3. Consume: Use the generated types in your application:
   • React Native: Use the useStore hook.
   • Swift (iOS): Use the @UseStore property wrapper.
   • Kotlin (Android): Use the Store API.
4. Sync: State changes are automatically synchronized between the TypeScript and native sides.

┌─────────────────┐       ┌──────────────────┐       ┌──────────────────────┐
│   TypeScript    │──────▶│  Brownfield CLI  │──────▶│  Swift/Kotlin types   │
│   Store Schema  │       │     (codegen)    │       │   (generated)        │
└─────────────────┘       └──────────────────┘       └──────────────────────┘

Brownie uses a multi-layered data flow model where data is passed between layers via full copies. There is no shared memory or zero-copy optimization currently implemented; each layer (JS, C++, and Swift/ObjC) maintains its own independent representation of the state.

Data Flow Path

1. JS Object (jsi) $\leftrightarrow$ (copy) $\leftrightarrow$ folly::dynamic (C++) $\leftrightarrow$ (copy) $\leftrightarrow$ NSDictionary / Swift (ObjC/Swift)

Performance Considerations

Because of the copying mechanism, the number of copies per operation varies:

• JS read/write single property: 2 copies.
• Swift read/write full state: 4 copies (involving JSON serialization/deserialization cycles).

Thread Safety

• The C++ store is protected by std::mutex during all operations.
• The Swift StoreManager uses NSLock for registry access.
• Change notifications are dispatched to the main queue using dispatch_async.

The @UseStore property wrapper provides reactive, type-safe access to a specific slice of the Brownfield state using a KeyPath selector.

Key features:

• Re-renders: The view only re-renders when the specifically selected value changes.
• Type Safety: Access is governed by the type of the selected KeyPath.
• Requirement: Selected values must conform to Equatable for change detection.
• Bindings: The projected value ($) provides a standard SwiftUI Binding<Value> for two-way data binding.

Updating State: Use the .set { ... } extension on the projected value to update state using a closure based on the current value.

import Brownie
import SwiftUI

struct CounterView: View {
  @UseStore(\BrownfieldStore.counter) var counter

  var body: some View {
    VStack {
      Text("Count: \(Int(counter))")

      Button("Increment") {
        $counter.set { $0 + 1 }
      }
    }
  }
}