Noções Básicas de Brownfield

10 exemplos para decidir quando incorporar React Native, reescrever em RN ou usar WebView como fallback - 7 básicos e 3 intermediários.

Pré-requisitos

O trabalho em Brownfield assume que você já envia um aplicativo nativo iOS e/ou Android cujo ponto de entrada principal não é React Native. Você adiciona RN como uma biblioteca, tela ou módulo de recurso.

Para integração prática após essas decisões, veja Visão Geral do expo-brownfield. Para limites de arquitetura dentro da fatia RN, veja Noções Básicas de Arquitetura Mobile.

# Spike: projeto Expo mínimo para validar viabilidade de incorporação
npx create-expo-app@latest RnSpike --template blank-typescript@sdk-57
cd RnSpike
npx expo install expo-brownfield

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. As APIs de integração Brownfield estão em alfa - reserve tempo para depuração de build nativo.

Exemplos Básicos

1. Brownfield vs Greenfield

Greenfield significa que React Native (ou Expo) é a raiz do aplicativo - cada tela se ramifica a partir de uma entrada JS. Brownfield significa que UIKit/Swift, Jetpack Compose/Kotlin ou outra pilha nativa possui o shell; RN é incorporado sob demanda.

Greenfield                          Brownfield
┌─────────────────────┐            ┌─────────────────────┐
│  Raiz RN (principal) │            │  Raiz Nativa        │
│  ├─ Aba A           │            │  ├─ Home (nativo)   │
│  ├─ Aba B           │            │  ├─ Configurações (nat.) │
│  └─ Modal           │            │  └─ Checkout (RN)   │  ← Ilha RN
└─────────────────────┘            └─────────────────────┘

• Se o seu AppDelegate / classe Application inicia um storyboard nativo primeiro, você está em brownfield
• O Dev Client do Expo não tem como alvo aplicativos host brownfield hoje - use Metro + artefatos de depuração ou prebuild integrado para desenvolvimento local
• Módulos do Expo SDK, Expo Router, EAS Build e EAS Submit suportam brownfield de acordo com a matriz de compatibilidade do Expo

Relacionado: Visão Geral do expo-brownfield - empacotando RN como AAR/XCFramework | ../architecture-design/mobile-architecture-basics/mobile-architecture-basics.md - estruturando a fatia RN uma vez incorporada

2. Incorporar React Native - Quando Vale a Pena

Incorpore RN quando o recurso precisar de UI com aparência nativa, comportamento offline/cache, APIs de dispositivo ou TypeScript compartilhado com uma equipe web - e a tela nativa legada levaria trimestres para ser reconstruída.

// A fatia RN ainda pode usar o Expo Router dentro do contêiner fornecido pelo host
// app/_layout.tsx - a navegação RN é interna ao 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>
  );
}

• Incorporar não requer reescrever o aplicativo inteiro - comece com um fluxo de alta rotatividade (checkout, onboarding, chat de suporte)
• Use artefatos isolados do expo-brownfield quando as equipes nativas recusarem Node no CI
• Planeje um projeto Metro por módulo incorporado - evite dois runtimes RN em um processo sem planejamento multipleFrameworks no iOS

Relacionado: RNHostView & Incorporação de UI Nativa - RN dentro de layouts SwiftUI/Compose | ../native-modules/native-modules-basics/native-modules-basics.md - quando apenas JS é insuficiente

3. Reescrita Completa - Quando Vale a Pena

Uma reescrita substitui o shell nativo por um aplicativo Expo/RN. Justificada quando a maioria das telas está mudando de qualquer maneira, os custos de navegação dupla excedem a migração, ou você precisa de um pipeline OTA para todo o produto.

Lista de verificação de decisão de reescrita (todos "sim" → forte caso de reescrita):
□ Nativo e web mobile compartilham uma biblioteca de componentes
□ Autenticação, push e links profundos precisam de roteamento unificado (Expo Router)
□ A equipe nativa não consegue sustentar duas pilhas de UI
□ A liderança aceita 2–4 sprints de congelamento de migração nos fluxos afetados

• Reescreitas falham quando tratadas como big-bang - use strangler fig (veja ADR de Adoção Incremental)
• A incorporação Brownfield é frequentemente a primeira fase de uma reescrita, não a alternativa a ela
• Documente a escolha em um ADR antes de re-plataformar listagens de lojas ou IDs de bundle

Relacionado: ADR de Adoção Incremental - decisões de strangler fig classificadas | ../architecture-design/adr-navigation-library-choice/adr-navigation-library-choice.md - Expo Router vs React Navigation durante a migração

4. Fallback de WebView - Quando Vale a Pena

WebView envia a web mobile dentro do shell nativo. Melhor para conteúdo somente leitura, raramente atualizado ou hospedado legalmente, onde UX nativa e offline não são metas.

import { WebView } from "react-native-webview";
 
export function HelpCenterWebView({ url }: { url: string }) {
  return (
    <WebView
      source={{ uri: url }}
      startInLoadingState
      sharedCookiesEnabled
      // O aplicativo host deve injetar cookie de autenticação ou token via injectedJavaScript
    />
  );
}

• O compartilhamento de cookies/sessão com o aplicativo nativo é frágil - planeje a entrega explícita de tokens (veja Autenticação Compartilhada e Bridges)
• WebView não oferece módulos Expo, Reanimated ou offline consistente - é uma aba de navegador com um ícone de aplicativo
• Prefira Safari View Controller / Chrome Custom Tabs para fluxos OAuth que proíbem WebViews incorporados

Relacionado: Autenticação Compartilhada e Bridges - passando sessões para WebView e RN

5. Matriz de Decisão Três Vias

Pontue cada recurso candidato de 1 a 5 nesses eixos; o total mais alto sugere a coluna.

Exemplo: "Rastreamento de pedidos" em um aplicativo de varejo nativo
  Complexidade da UI: 4  |  Offline: 3  |  Cadência: 5  |  TS Compartilhado: 4
  → Incorporar RN (strangler fig na pilha de rastreamento)
 
Exemplo: "Termos de serviço"
  UI: 1  |  Offline: 0  |  Cadência: 1
  → WebView ou SFSafariViewController

• Nenhuma coluna vence todas as linhas - documente a pontuação em seu repositório ADR
• Revise quando EAS Update ou política da loja mudarem - o checkout apenas com WebView pode falhar na revisão

Relacionado: ADR de Adoção Incremental - decisões classificadas formais por cenário

6. Incorporação Integrada vs. Isolada

O Expo documenta duas formas de brownfield:

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

# Esquadrão RN publica artefatos; esquadrão nativo consome Maven / Swift Package
npx expo-brownfield build:android --release
npx expo-brownfield build:ios --release --package CheckoutPackage

• Isolada é a recomendação padrão quando os trens de lançamento nativos não podem absorver Yarn/Metro
• Integrada se encaixa quando você já executa npx expo prebuild dentro do repositório host
• Ambas as abordagens ainda precisam de um Hermes + versão RN alinhada com o SDK 57

Relacionado: Visão Geral do expo-brownfield - cookbook completo | ../native-modules/config-plugins/config-plugins.md - opções do plugin expo-brownfield

7. Apresentando a Primeira Tela RN (Lado do Host)

O aplicativo host inicializa o runtime RN uma vez e, em seguida, apresenta um view controller ou activity.

// iOS - chamar cedo no AppDelegate
import CheckoutBrownfield
 
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    ReactNativeHostManager.shared.initialize()
    return true
  }
}
 
// UIKit - empurrar checkout do React Native
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 deve corresponder ao registro main em registerRootComponent / app.json no projeto RN
• initialProps semeia parâmetros de rota - combine com chaves de autenticação compartilhadas (próximo artigo)
• Builds de depuração carregam do Metro (npx expo start); builds de lançamento usam o bundle incorporado dentro do artefato

Relacionado: CI/CD Brownfield - pipelines de artefatos de depuração vs. lançamento

Exemplos Intermediários

8. Strangler Fig - Seleção da Primeira Fatia

Escolha um fluxo que seja doloroso em nativo, delimitado e não no caminho crítico de inicialização a frio.

Boas primeiras fatias:
  ✓ Dashboard pós-login (autenticação já nativa)
  ✓ Subfluxo de configurações raramente aberto no lançamento
  ✓ Novo recurso sem código legado
 
Más primeiras fatias:
  ✗ Splash de inicialização do aplicativo / aba inicial (custo de inicialização a frio + inicialização RN)
  ✗ Hub de navegação nativa profunda (propriedade da pilha de retorno incerta)
  ✗ Tarefas em segundo plano / widgets (RN não em processo)

// Lado RN - escutar mensagens "abrir fatia" nativas
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();
  }, []);
}

• O nativo ainda possui a barra de abas e a navegação raiz até que o strangler aposente essas telas
• Use Brownfield.popToNative() quando o RN terminar um fluxo e devolver o controle para UIKit/Compose
• Registre a ordem da fatia no ADR de Adoção Incremental

Relacionado: Autenticação Compartilhada e Bridges - contrato BrownfieldMessaging

9. WebView vs RN para a Mesma Tela de Produto

Quando o gerente de produto pede "apenas use o site mobile", execute esta comparação em uma tela.

// Compromisso: WebView para spike MVP, RN para v2 - controlar com flag de recurso
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" />;
}

• Limite de tempo para spikes de WebView - não deixe shells temporários se tornarem permanentes sem um ADR
• Se a página web precisar de câmera ou upload de arquivos, o encanamento de permissões do WebView geralmente excede o custo do RN

Relacionado: ../architecture-design/modular-monolith-vs-multi-app/modular-monolith-vs-multi-app.md - flags de recursos vs. aplicativos separados

10. Limites de Propriedade em um Aplicativo Híbrido

Defina quem é o proprietário de cada camada antes que o primeiro PR seja enviado.

Esquadrão Nativo é proprietário de:
  - Inicialização do aplicativo, registro push, cofre de keychain/sessão
  - Apresentação de ReactNativeViewController / BrownfieldActivity
  - Binários da loja, assinatura, triagem de falhas nativas
 
Esquadrão RN é proprietário de:
  - Projeto Metro, pino do Expo SDK, qualidade do bundle JS
  - Telas dentro do módulo incorporado, política OTA (se habilitada)
  - Atualizações de versão do artefato expo-brownfield
 
Contrato compartilhado (documentar no repositório):
  - Tipos de mensagem: OPEN_*, SESSION_*, LOGOUT
  - Chaves de estado compartilhadas: auth.accessToken, auth.userId
  - Versionamento semântico em AAR/Maven + iOS Swift Package

// Versione o contrato da bridge - alterações que quebram exigem bump de artefato principal
export const BRIDGE_CONTRACT_VERSION = "1.2.0";
 
export type HostToRnMessage =
  | { type: "SESSION_UPDATED"; accessToken: string; userId: string }
  | { type: "OPEN_CHECKOUT"; cartId: string };

• Um bundler Metro por módulo incorporado - duas instâncias RN sem multipleFrameworks: true no iOS correm risco de símbolos duplicados
• Alinhe com as Melhores Práticas de Brownfield antes de escalar para várias fatias

Relacionado: Melhores Práticas de Brownfield - resumo de 25 itens | ../native-modules/autolinking-and-expo-modules-core/autolinking-and-expo-modules-core.md - autolinking em monorepos

FAQs

Relacionados

• Visão Geral do expo-brownfield - construa AAR/XCFramework e conecte o aplicativo host
• ADR de Adoção Incremental - decisões classificadas de strangler fig
• Autenticação Compartilhada e Bridges - sessões entre nativo e RN
• ../architecture-design/mobile-architecture-basics/mobile-architecture-basics.md - fatias de recursos dentro do projeto RN
• ../native-modules/config-plugins/config-plugins.md - plugin de configuração expo-brownfield

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).