Brownfield Basics

# Spike: minimal Expo project to validate embed feasibility
npx create-expo-app@latest RnSpike --template blank-typescript@sdk-57
cd RnSpike
npx expo install expo-brownfield

Greenfield                          Brownfield
┌─────────────────────┐            ┌─────────────────────┐
│  RN root (main)     │            │  Native root        │
│  ├─ Tab A           │            │  ├─ Home (native)   │
│  ├─ Tab B           │            │  ├─ Settings (nat.) │
│  └─ Modal           │            │  └─ Checkout (RN)   │  ← RN island
└─────────────────────┘            └─────────────────────┘

// The RN slice can still use Expo Router inside the host-provided container
// app/_layout.tsx - RN navigation is internal to the embedded module
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="checkout" />
      <Stack.Screen name="order-confirmation" />
    </Stack>
  );
}

Rewrite decision checklist (all "yes" → strong rewrite case):
□ Native and mobile web share a component library
□ Auth, push, and deep links need unified routing (Expo Router)
□ Native headcount cannot sustain two UI stacks
□ Leadership accepts 2–4 sprint migration freeze on affected flows

import { WebView } from "react-native-webview";
 
export function HelpCenterWebView({ url }: { url: string }) {
  return (
    <WebView
      source={{ uri: url }}
      startInLoadingState
      sharedCookiesEnabled
      // Host app must inject auth cookie or token via injectedJavaScript
    />
  );
}

Example: "Order tracking" in a native retail app
  UI complexity: 4  |  Offline: 3  |  Cadence: 5  |  Shared TS: 4
  → Embed RN (strangler fig on tracking stack)
 
Example: "Terms of service"
  UI: 1  |  Offline: 0  |  Cadence: 1
  → WebView or SFSafariViewController

// app.config.ts - isolated path uses expo-brownfield config plugin
export default {
  expo: {
    plugins: [
      [
        "expo-brownfield",
        {
          ios: { targetName: "CheckoutBrownfield" },
          android: {
            group: "com.example",
            libraryName: "checkout-brownfield",
            version: "2.1.0",
          },
        },
      ],
    ],
  },
};

# RN squad publishes artifacts; native squad consumes Maven / Swift Package
npx expo-brownfield build:android --release
npx expo-brownfield build:ios --release --package CheckoutPackage

// iOS - call early in AppDelegate
import CheckoutBrownfield
 
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    ReactNativeHostManager.shared.initialize()
    return true
  }
}
 
// UIKit - push RN checkout
let vc = ReactNativeViewController(
  moduleName: "main",
  initialProps: ["cartId": cartId]
)
navigationController?.pushViewController(vc, animated: true)

// Android - BrownfieldActivity + fragment
class CheckoutActivity : BrownfieldActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    showReactNativeFragment()
  }
}

Good first slices:
  ✓ Post-login dashboard (auth already native)
  ✓ Settings sub-flow rarely opened at launch
  ✓ New feature with no legacy code
 
Poor first slices:
  ✗ App launch splash / home tab (cold start + RN init cost)
  ✗ Deep native navigation hub (back-stack ownership unclear)
  ✗ Background tasks / widgets (RN not in process)

// RN side - listen for native "open slice" messages
import * as Brownfield from "expo-brownfield";
import { useEffect } from "react";
import { router } from "expo-router";
 
export function useNativeDeepLinks() {
  useEffect(() => {
    const sub = Brownfield.addMessageListener((event) => {
      if (event.type === "OPEN_TRACKING" && event.orderId) {
        router.push(`/orders/${event.orderId}`);
      }
    });
    return () => sub.remove();
  }, []);
}

// Compromise: WebView for MVP spike, RN for v2 - gate with feature flag
import { useFeatureFlag } from "@/shared/feature-flags";
 
export function LoyaltyScreen() {
  const useNative = useFeatureFlag("loyalty_rn_v2");
  return useNative ? <LoyaltyNative /> : <LoyaltyWebView uri="https://m.example.com/loyalty" />;
}

Native squad owns:
  - App launch, push registration, keychain/session vault
  - Presenting ReactNativeViewController / BrownfieldActivity
  - Store binaries, signing, native crash triage
 
RN squad owns:
  - Metro project, Expo SDK pin, JS bundle quality
  - Screens inside the embedded module, OTA policy (if enabled)
  - expo-brownfield artifact version bumps
 
Shared contract (document in repo):
  - Message types: OPEN_*, SESSION_*, LOGOUT
  - Shared state keys: auth.accessToken, auth.userId
  - Semantic versioning on AAR/Maven + iOS Swift Package

// Version the bridge contract - breaking changes require major artifact bump
export const BRIDGE_CONTRACT_VERSION = "1.2.0";
 
export type HostToRnMessage =
  | { type: "SESSION_UPDATED"; accessToken: string; userId: string }
  | { type: "OPEN_CHECKOUT"; cartId: string };