Noções Básicas de Módulos Nativos

Dez exemplos para quando soluções apenas em JavaScript falham e você precisa cruzar a fronteira nativa - a base que toda equipe do Expo SDK 57 precisa antes de adicionar bibliotecas de terceiros, plugins de configuração ou módulos personalizados.

Pré-requisitos

Comece com um aplicativo Expo em branco com um caminho de build de desenvolvimento pronto - módulos nativos não são executados no Jest sem mocks e não podem carregar código arbitrário no Expo Go:

npx create-expo-app@latest NativeBasics --template blank-typescript@sdk-57 --yes
cd NativeBasics
npx expo install expo-dev-client expo-modules-core

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. Combine esta página com Regras de Módulos Nativos antes de adicionar qualquer pacote com código nativo.

Exemplos Básicos

1. Quando APIs de Hardware Não Têm Equivalente em JS

Frames de câmera, correções de GPS, fluxos de acelerômetro e sensores biométricos leem hardware do dispositivo através de APIs do sistema operacional. JavaScript não pode acessá-los sem um módulo nativo:

import { CameraView, useCameraPermissions } from "expo-camera";
import { Button } from "react-native";
 
export function ScanScreen() {
  const [permission, requestPermission] = useCameraPermissions();
 
  if (!permission?.granted) {
    return <Button title="Permitir câmera" onPress={requestPermission} />;
  }
 
  return <CameraView style={{ flex: 1 }} facing="back" />;
}

• expo-camera envolve AVFoundation (iOS) e CameraX (Android) - nenhum substituto puramente em JS
• Solicitações de permissão exigem entradas Info.plist e AndroidManifest - plugins de configuração lidam com isso
• Expo Go inclui expo-camera; SDKs de câmera arbitrários não incluem

2. Quando o Armazenamento Seguro Deve Usar Keychain / Keystore

AsyncStorage é SQLite sem criptografia. Tokens, segredos de atualização e PII pertencem ao Keychain (iOS) ou Keystore (Android):

import * as SecureStore from "expo-secure-store";
 
export async function saveRefreshToken(token: string): Promise<void> {
  await SecureStore.setItemAsync("refresh_token", token, {
    keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
  });
}
 
export async function loadRefreshToken(): Promise<string | null> {
  return SecureStore.getItemAsync("refresh_token");
}

• Criptografia baseada em hardware é uma capacidade nativa - padrões localStorage da web não se aplicam
• Veja SecureStore & Keychain/Keystore para padrões de rotação e multi-conta
• Testes Jest devem simular expo-secure-store - veja Simulando Módulos Nativos

3. Quando o Trabalho em Segundo Plano Excede os Limites da Thread JS

Timers e fetch pausam quando o aplicativo está em segundo plano ou é encerrado. Entrega de push, atualizações de localização e uploads em segundo plano exigem agendadores nativos:

import * as TaskManager from "expo-task-manager";
import * as Location from "expo-location";
 
const TASK_NAME = "background-location";
 
TaskManager.defineTask(TASK_NAME, ({ data, error }) => {
  if (error) return;
  const { locations } = data as { locations: Location.LocationObject[] };
  // Envie as localizações para sua API - a tarefa nativa continua disparando
});
 
export async function startBackgroundLocation(): Promise<void> {
  await Location.startLocationUpdatesAsync(TASK_NAME, {
    accuracy: Location.Accuracy.Balanced,
    distanceInterval: 100,
    showsBackgroundLocationIndicator: true,
  });
}

• Modos de segundo plano exigem permissões e flags de manifesto - nunca edite manualmente após pré-build do CNG
• O iOS encerra aplicativos que reivindicam capacidade de segundo plano sem uso real - a revisão da App Store rejeita modos fantasmas

4. Quando Notificações Push Precisam de Tokens Nativos APNs / FCM

Push não é polling HTTP. Tokens de dispositivo vêm de SDKs nativos do Apple Push Notification service e Firebase Cloud Messaging:

import * as Notifications from "expo-notifications";
import * as Device from "expo-device";
 
export async function registerPushToken(): Promise<string | null> {
  if (!Device.isDevice) return null;
 
  const { status } = await Notifications.requestPermissionsAsync();
  if (status !== "granted") return null;
 
  const token = await Notifications.getExpoPushTokenAsync();
  return token.data;
}

• O comportamento de push do simulador difere do dispositivo - sempre verifique no hardware antes do lançamento
• Extensões de notificação personalizadas (mídia rica, categorias) são totalmente nativas - JS orquestra, nativo renderiza

5. Quando Você Precisa de Componentes de UI Nativos

Algumas visualizações não podem ser reproduzidas fielmente no layout do React Native - mapas, players de vídeo, renderizadores de PDF e WebViews incorporam visualizações nativas da plataforma dentro da árvore RN:

import MapView, { Marker } from "react-native-maps";
 
export function StoreMap({ lat, lng }: { lat: number; lng: number }) {
  return (
    <MapView
      style={{ flex: 1 }}
      initialRegion={{
        latitude: lat,
        longitude: lng,
        latitudeDelta: 0.02,
        longitudeDelta: 0.02,
      }}
    >
      <Marker coordinate={{ latitude: lat, longitude: lng }} title="Loja" />
    </MapView>
  );
}

• Visualizações nativas participam da árvore de sombras do Fabric na Nova Arquitetura - props de layout ainda se aplicam ao contêiner
• SDKs de mapas de terceiros enviam seus próprios binários nativos - avalie a compatibilidade antes de npm install

6. Quando APIs Apenas da Plataforma Bloqueiam Seu Recurso

HealthKit, NFC, CarPlay, atalhos da Siri e intents do Android existem apenas em uma plataforma. A detecção de recursos impede o JS; módulos nativos implementam a chamada:

import { Platform } from "react-native";
import * as LocalAuthentication from "expo-local-authentication";
 
export async function biometricGate(): Promise<boolean> {
  if (Platform.OS === "web") return false;
 
  const compatible = await LocalAuthentication.hasHardwareAsync();
  if (!compatible) return false;
 
  const enrolled = await LocalAuthentication.isEnrolledAsync();
  if (!enrolled) return false;
 
  const result = await LocalAuthentication.authenticateAsync({
    promptMessage: "Desbloqueie para continuar",
  });
  return result.success;
}

• Verificações Platform.OS evitam travamentos; elas não substituem a implementação nativa
• Módulos específicos da plataforma devem expor uma API unificada de TypeScript na camada do seu aplicativo - oculte Platform.select dentro de serviços

7. Quando Trabalho Crítico de Desempenho Deve Sair da Thread JS

Transformações pesadas de imagem, codificação de vídeo, criptografia e inferência de ML bloqueiam a thread JS se feitas em JavaScript puro. Módulos nativos executam trabalho em filas de segundo plano ou caminhos de GPU:

import * as ImageManipulator from "expo-image-manipulator";
 
export async function resizeAvatar(uri: string): Promise<string> {
  const result = await ImageManipulator.manipulateAsync(
    uri,
    [{ resize: { width: 256 } }],
    { compress: 0.8, format: ImageManipulator.SaveFormat.JPEG }
  );
  return result.uri;
}

• Hermes é rápido para lógica de aplicativo - não é um substituto para Core Image, MediaCodec ou C++ SIMD
• Perfure no dispositivo: se as quedas de quadros do JS coincidirem com sua função, mova o trabalho para nativo ou para um worker

8. Quando Integrações de Sistema Exigem Pontos de Entrada Nativos

Folhas de compartilhamento, widgets na tela inicial, App Clips e links universais são registrados na camada de aplicativo nativo. JavaScript recebe eventos de deep-link; o código nativo é o proprietário do registro:

import * as Linking from "expo-linking";
 
export function subscribeToDeepLinks(onUrl: (url: string) => void): () => void {
  const sub = Linking.addEventListener("url", ({ url }) => onUrl(url));
  Linking.getInitialURL().then((url) => {
    if (url) onUrl(url);
  });
  return () => sub.remove();
}

// trecho do app.json - domínios associados são permissões nativas
{
  "expo": {
    "scheme": "myapp",
    "ios": {
      "associatedDomains": ["applinks:shop.example.com"]
    }
  }
}

• Domínios associados e filtros de intent do Android são aplicados durante o pré-build - expresse-os na configuração, não em edições manuais de Info.plist

9. Quando Bluetooth / BLE Precisa de Pilhas Nativas GATT

Web Bluetooth não está disponível no React Native. Escaneamento BLE, emparelhamento e leitura/escrita GATT exigem CoreBluetooth (iOS) e BluetoothGatt (Android):

// Conceitual - bibliotecas BLE reais expõem módulos nativos
import { BleManager } from "react-native-ble-plx";
 
const manager = new BleManager();
 
export async function scanForPeripherals(): Promise<void> {
  manager.startDeviceScan(null, null, (error, device) => {
    if (error) return;
    if (device?.name) console.log("Encontrado", device.name);
  });
}

• Bibliotecas BLE nunca estão no Expo Go - planeje expo-dev-client desde o início
• BLE em segundo plano no iOS requer permissões adicionais e consome bateria - documente em seu ADR

10. Quando Polyfills JS Não Podem Satisfazer Requisitos da Loja ou de Segurança

Às vezes, a lacuna não é capacidade, mas conformidade: fixação de certificado, detecção de jailbreak, SDKs de pagamento proprietários ou APIs exigidas pelo MDM. Estes são enviados como binários nativos sem equivalente no Expo SDK:

// Fachada da camada de aplicativo - a implementação é um módulo nativo ou SDK de terceiros
export type AttestationResult = { passed: boolean; reason?: string };
 
export async function attestDevice(): Promise<AttestationResult> {
  // Módulo nativo: DeviceCheck (iOS) / Play Integrity (Android)
  const NativeAttestation = require("../native/attestation").default;
  return NativeAttestation.runAsync();
}

• Revisão da loja pode exigir versões específicas do SDK nativo - wrappers JS devem corresponder a builds nativos fixados
• Qualquer solução alternativa apenas com polyfill que toque na segurança deve ser rejeitada na revisão de código - veja Regras de Módulos Nativos

Como Módulos Nativos Carregam no SDK 57

JavaScript (Hermes)
    │
    ▼
expo-modules-core / objeto host JSI
    │
    ├── API Expo Modules (expo-camera, expo-file-system, …)
    ├── React Native TurboModules (bibliotecas da comunidade)
    └── Fallback de bridge legado (apenas bibliotecas mais antigas)
    │
    ▼
Implementação nativa Swift / Kotlin / C++

import { requireNativeModule, requireOptionalNativeModule } from "expo-modules-core";
 
// Lança erro se a classe nativa estiver faltando no binário
const FileSystem = requireNativeModule("ExpoFileSystem");
 
// Retorna null em testes ou quando o módulo não está vinculado
const Optional = requireOptionalNativeModule("ExpoCustomFeature");

Veja Expo Modules Core para detalhes de bootstrap e Expo Go vs Builds de Desenvolvimento para restrições de tempo de execução.

Armadilhas

• Esperar que o Expo Go carregue qualquer pacote npm nativo - apenas módulos pré-instalados funcionam. Correção: npx expo install expo-dev-client e crie um cliente de desenvolvimento.
• Instalar com npm install em vez de npx expo install - versões de binários JS e nativos divergem. Correção: Sempre npx expo install <pacote> para dependências nativas.
• Pular reconstrução nativa após alteração no package.json - a recarga a quente do Metro não compila Swift/Kotlin. Correção: npx expo run:ios / eas build após cada alteração nativa.
• Chamar módulos nativos no nível superior do módulo em testes - Jest não tem bridge. Correção: Simular na fronteira do serviço ou usar jest-expo.
• Editar manualmente ios/ e android/ em aplicativos CNG - o próximo prebuild --clean apaga as edições. Correção: Codificar alterações em plugins de configuração conforme Pré-build CNG.

FAQs

Relacionados

• Usando Bibliotecas Nativas de Terceiros - checklist de compatibilidade
• Plugins de Configuração - permissões e alterações de manifesto
• create-expo-module - estrutura de um módulo local
• Regras de Módulos Nativos - checklist de decisão
• Noções Básicas de Pré-build - gerando projetos nativos
• Expo Modules Core - detalhes internos do carregador JSI
• Expo Go vs Builds de Desenvolvimento - limites de tempo de execução
• Simulando Módulos Nativos - Jest sem bridge

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).