Fundamentos de Brownfield

10 ejemplos para decidir cuándo incorporar React Native, reescribir en RN o usar WebView como alternativa - 7 básicos y 3 intermedios.

Requisitos previos

El trabajo brownfield asume que ya distribuyes una app nativa de iOS y/o Android cuyo punto de entrada principal no es React Native. Añades RN como una biblioteca, pantalla o módulo de característica.

Para integración práctica después de estas decisiones, ver Descripción general de expo-brownfield. Para límites de arquitectura dentro de la porción RN, ver Fundamentos de Arquitectura Móvil.

# Spike: proyecto Expo mínimo para validar viabilidad de incorporación
npx create-expo-app@latest RnSpike --template blank-typescript@sdk-57
cd RnSpike
npx expo install expo-brownfield

Tooling: Estos ejemplos tienen como objetivo Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 y React 19.2.3. Las APIs de integración brownfield están en alpha - presupuesta tiempo para debugging de compilación nativa.

Ejemplos básicos

1. Brownfield vs Greenfield

Greenfield significa que React Native (o Expo) es la raíz de la app - cada pantalla se ramifica desde una entrada JS. Brownfield significa que UIKit/Swift, Jetpack Compose/Kotlin u otro stack nativo posee el shell; RN se incorpora bajo demanda.

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

• Si tu AppDelegate / Application class lanza un storyboard nativo primero, eres brownfield
• Expo Dev Client no apunta a apps host brownfield hoy - usa Metro + debug artifacts o prebuild integrado para dev local
• Módulos Expo SDK, Expo Router, EAS Build y EAS Submit soportan brownfield según la matriz de compatibilidad de Expo

Relacionado: Descripción general de expo-brownfield - empaquetando RN como AAR/XCFramework | ../architecture-design/mobile-architecture-basics/mobile-architecture-basics.md - estructurando la porción RN una vez incorporada

2. Incorporar React Native - Cuándo gana

Incorpora RN cuando la característica necesite UI con sentimiento nativo, comportamiento offline/cache, APIs de dispositivo o TypeScript compartido con un equipo web - y la pantalla nativa heredada tomaría trimestres para reconstruir.

// La porción RN puede usar Expo Router dentro del contenedor proporcionado por el host
// app/_layout.tsx - la navegación RN es interna al módulo incorporado
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="checkout" />
      <Stack.Screen name="order-confirmation" />
    </Stack>
  );
}

• La incorporación no requiere reescribir toda la app - comienza con un flujo de alta rotación (checkout, onboarding, support chat)
• Usa artefactos aislados de expo-brownfield cuando los equipos nativos rechazan Node en CI
• Planifica un proyecto Metro por módulo incorporado - evita dos runtimes RN en un proceso sin planeamiento de multipleFrameworks en iOS

Relacionado: RNHostView & Incorporación de UI Nativa - RN dentro de layouts de SwiftUI/Compose | ../native-modules/native-modules-basics/native-modules-basics.md - cuando solo JS es insuficiente

3. Reescritura completa - Cuándo gana

Una reescritura reemplaza el shell nativo con una app Expo/RN. Justificada cuando la mayoría de pantallas están cambiando de todos modos, los costos de navegación dual exceden la migración, o necesitas un pipeline OTA para todo el producto.

Lista de verificación de decisión de reescritura (todos "sí" - caso de reescritura fuerte):
□ Nativo y web móvil comparten una librería de componentes
□ Auth, push y deep links necesitan enrutamiento unificado (Expo Router)
□ La capacidad nativa no puede sostener dos stacks UI
□ El liderazgo acepta 2-4 sprints de congelación de migración en flujos afectados

• Las reescrituras fallan cuando se tratan como big-bang - usa strangler fig (ver ADR de Adopción Incremental)
• La incorporación brownfield a menudo es la primera fase de una reescritura, no la alternativa a una
• Documenta la elección en un ADR antes de re-plataformar listados de tienda o IDs de bundle

Relacionado: ADR de Adopción Incremental - decisiones strangler fig clasificadas | ../architecture-design/adr-navigation-library-choice/adr-navigation-library-choice.md - Expo Router vs React Navigation durante migración

4. Alternativa WebView - Cuándo gana

WebView distribuye web móvil dentro del shell nativo. Mejor para contenido solo lectura, rara vez actualizado o legalmente alojado donde UX nativa y offline no son objetivos.

import { WebView } from "react-native-webview";
 
export function HelpCenterWebView({ url }: { url: string }) {
  return (
    <WebView
      source={{ uri: url }}
      startInLoadingState
      sharedCookiesEnabled
      // La app host debe inyectar cookie de auth o token vía injectedJavaScript
    />
  );
}

• Compartición de cookie/sesión con la app nativa es frágil - planifica handoff de token explícito (ver Autenticación compartida y Bridges)
• WebView no te da módulos Expo, Reanimated u offline consistente - es una pestaña de navegador con un icono de app
• Prefiere Safari View Controller / Chrome Custom Tabs para flujos OAuth que prohíben WebViews incorporadas

Relacionado: Autenticación compartida y Bridges - pasando sesiones en WebView y RN

5. Matriz de decisión de tres vías

Puntúa cada característica candidata 1-5 en estos ejes; el total más alto sugiere la columna.

Ejemplo: "Order tracking" en una app nativa de retail
  Complejidad UI: 4  |  Offline: 3  |  Cadencia: 5  |  TS compartido: 4
  - Incorporar RN (strangler fig en stack de tracking)
 
Ejemplo: "Terms of service"
  UI: 1  |  Offline: 0  |  Cadencia: 1
  - WebView o SFSafariViewController

• Ninguna columna gana cada fila - documenta la puntuación en tu repo ADR
• Revisa cuando EAS Update o política de tienda cambie - checkout solo con WebView puede fallar revisión

Relacionado: ADR de Adopción Incremental - decisiones clasificadas formales por escenario

6. Incorporación integrada vs aislada

Expo documenta dos formas brownfield:

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

# Escuadra RN publica artefactos; escuadra nativa consume Maven / Swift Package
npx expo-brownfield build:android --release
npx expo-brownfield build:ios --release --package CheckoutPackage

• Aislado es la recomendación por defecto cuando trenes de lanzamiento nativos no pueden absorber Yarn/Metro
• Integrado encaja cuando ya ejecutas npx expo prebuild dentro del repo host
• Ambos enfoques aún necesitan una versión Hermes + RN alineada con SDK 57

Relacionado: Descripción general de expo-brownfield - libro de recetas completo | ../native-modules/config-plugins/config-plugins.md - opciones de plugin expo-brownfield

7. Presentando la primera pantalla RN (lado del host)

La app host inicializa el runtime RN una vez, luego presenta un view controller o activity.

// iOS - llama temprano en 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 checkout RN
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()
  }
}

• moduleName debe coincidir con registerRootComponent / registro main de app.json en el proyecto RN
• initialProps proporciona parámetros de ruta - empareja con claves de auth compartidas (próximo artículo)
• Las compilaciones de debug cargan desde Metro (npx expo start); las compilaciones de lanzamiento usan el bundle incorporado dentro del artefacto

Relacionado: Brownfield CI/CD - pipelines de artefactos debug vs release

Ejemplos intermedios

8. Strangler Fig - Selección de primera porción

Elige un flujo que sea doloroso en nativo, acotado y no en la ruta de inicio en frío crítica.

Buenas primeras porciones:
  ✓ Dashboard post-login (auth ya nativo)
  ✓ Sub-flujo de settings rara vez abierto al lanzamiento
  ✓ Nueva característica sin código heredado
 
Malas primeras porciones:
  ✗ Splash de lanzamiento de app / pestaña home (inicio frío + costo de init RN)
  ✗ Hub de navegación nativa profunda (propiedad de back-stack poco clara)
  ✗ Tareas de fondo / widgets (RN no en proceso)

// Lado RN - escucha mensajes "open slice" nativos
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();
  }, []);
}

• Nativo aún posee barra de pestañas y navegación raíz hasta que el strangler retire esas pantallas
• Usa Brownfield.popToNative() cuando RN termina un flujo y devuelve control a UIKit/Compose
• Registra orden de porción en ADR de Adopción Incremental

Relacionado: Autenticación compartida y Bridges - contrato BrownfieldMessaging

9. WebView vs RN para la misma pantalla de producto

Cuando PM pide "solo usa el sitio móvil", ejecuta esta comparación en una pantalla.

// Compromiso: WebView para spike MVP, RN para v2 - puerta con 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" />;
}

• Timeboxea spikes de WebView - no dejes shells temporales convertirse en permanentes sin un ADR
• Si la página web necesita cámara o carga de archivo, la plomería de permisos de WebView a menudo excede el costo de RN

Relacionado: ../architecture-design/modular-monolith-vs-multi-app/modular-monolith-vs-multi-app.md - feature flags vs apps separadas

10. Límites de propiedad en una app híbrida

Define quién posee cada capa antes de que llegue el primer PR.

Escuadra nativa posee:
  - Lanzamiento de app, registro de push, keychain/bóveda de sesión
  - Presentación de ReactNativeViewController / BrownfieldActivity
  - Binarios de tienda, firma, triage de crashes nativos
 
Escuadra RN posee:
  - Proyecto Metro, pin de Expo SDK, calidad de bundle JS
  - Pantallas dentro del módulo incorporado, política OTA (si está habilitada)
  - Bumps de versión de artefacto expo-brownfield
 
Contrato compartido (documenta en repo):
  - Tipos de mensaje: OPEN_*, SESSION_*, LOGOUT
  - Claves de estado compartido: auth.accessToken, auth.userId
  - Semantic versioning en AAR/Maven + iOS Swift Package

// Versiona el contrato del bridge - cambios de ruptura requieren bump de artefacto mayor
export const BRIDGE_CONTRACT_VERSION = "1.2.0";
 
export type HostToRnMessage =
  | { type: "SESSION_UPDATED"; accessToken: string; userId: string }
  | { type: "OPEN_CHECKOUT"; cartId: string };

• Un bundler Metro por módulo incorporado - dos instancias RN sin multipleFrameworks: true en iOS arriesgan símbolos duplicados
• Alinea con Prácticas recomendadas de Brownfield antes de escalar a múltiples porciones

Relacionado: Prácticas recomendadas de Brownfield - resumen de 25 elementos | ../native-modules/autolinking-and-expo-modules-core/autolinking-and-expo-modules-core.md - autolinking en monorepos

Preguntas frecuentes

Relacionado

• Descripción general de expo-brownfield - construye AAR/XCFramework y conecta la app host
• ADR de Adopción Incremental - decisiones strangler fig clasificadas
• Autenticación compartida y Bridges - sesiones entre nativo y RN
• ../architecture-design/mobile-architecture-basics/mobile-architecture-basics.md - porciones de característica dentro del proyecto RN
• ../native-modules/config-plugins/config-plugins.md - plugin de config expo-brownfield

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).