Fundamentos de Módulos Nativos

Diez ejemplos de cuándo las soluciones solo JavaScript fallan y debes cruzar el límite nativo - la base que cada equipo de Expo SDK 57 necesita antes de agregar bibliotecas de terceros, plugins de configuración o módulos personalizados.

Requisitos previos

Comienza desde una aplicación Expo en blanco con una ruta de compilación de desarrollo lista - los módulos nativos no se ejecutan en Jest sin mocks y no pueden cargar código arbitrario en 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

Herramientas: Estos ejemplos se dirigen a Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 y React 19.2.3. Empareja esta página con Reglas de Módulos Nativos antes de agregar cualquier paquete con código nativo.

Ejemplos básicos

1. Cuando las APIs de hardware no tienen equivalente en JS

Los fotogramas de cámara, fijaciones de GPS, flujos de acelerómetro y sensores biométricos leen hardware del dispositivo a través de APIs del SO. JavaScript no puede acceder a ellos sin un 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="Allow camera" onPress={requestPermission} />;
  }
 
  return <CameraView style={{ flex: 1 }} facing="back" />;
}

• expo-camera envuelve AVFoundation (iOS) y CameraX (Android) - sin sustituto puro en JS
• Los prompts de permisos requieren entradas en Info.plist y AndroidManifest - los plugins de configuración se encargan de esto
• Expo Go incluye expo-camera; los SDKs de cámara arbitrarios no

2. Cuando el almacenamiento seguro debe usar Keychain / Keystore

AsyncStorage es SQLite sin cifrar. Los tokens, secretos de actualización e información personal pertenecen a Keychain (iOS) o 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");
}

• El cifrado respaldado por hardware es una capacidad nativa - los patrones de localStorage web no aplican
• Ver SecureStore & Keychain/Keystore para patrones de rotación y múltiples cuentas
• Las pruebas de Jest deben mockear expo-secure-store - ver Mocking Native Modules

3. Cuando el trabajo en segundo plano excede los límites del hilo de JS

Los timers y fetch se pausan cuando la aplicación está en segundo plano o se ha eliminado. La entrega de push, actualizaciones de ubicación y cargas en segundo plano necesitan programadores 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[] };
  // Carga ubicaciones a tu API - la tarea nativa sigue disparándose
});
 
export async function startBackgroundLocation(): Promise<void> {
  await Location.startLocationUpdatesAsync(TASK_NAME, {
    accuracy: Location.Accuracy.Balanced,
    distanceInterval: 100,
    showsBackgroundLocationIndicator: true,
  });
}

• Los modos de segundo plano requieren derechos y flags de manifiesto - nunca edites manualmente después del prebuild de CNG
• iOS mata aplicaciones que reclaman capacidad de segundo plano sin uso real - la revisión de App Store rechaza modos fantasma

4. Cuando las notificaciones push necesitan tokens nativos de APNs / FCM

Push no es polling HTTP. Los tokens del dispositivo provienen de Apple Push Notification service y Firebase Cloud Messaging SDKs nativos:

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;
}

• El comportamiento de push en simulador difiere del dispositivo - siempre verifica en hardware antes del lanzamiento
• Las extensiones de notificación personalizada (medios ricos, categorías) son completamente nativas - JS orquesta, nativo renderiza

5. Cuando necesitas componentes de UI nativos

Algunas vistas no pueden reproducirse fielmente en el layout de React Native - mapas, reproductores de video, renderizadores PDF y WebViews incrustan vistas nativas de plataforma dentro del árbol 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="Store" />
    </MapView>
  );
}

• Las vistas nativas participan en el árbol de sombra Fabric en Nueva Arquitectura - los props de layout aún aplican al contenedor
• Los SDKs de mapas de terceros envían sus propios binarios nativos - evalúa la compatibilidad antes de npm install

6. Cuando las APIs específicas de plataforma bloquean tu característica

HealthKit, NFC, CarPlay, atajos de Siri e intents de Android existen solo en una plataforma. La detección de características cierra JS; los módulos nativos implementan la llamada:

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: "Unlock to continue",
  });
  return result.success;
}

• Los checks Platform.OS previenen crashes; no reemplazan la implementación nativa
• Los módulos específicos de plataforma deben exponer una API unificada de TypeScript en tu capa de aplicación - oculta Platform.select dentro de servicios

7. Cuando el trabajo crítico de rendimiento debe dejar el hilo de JS

Las transformaciones de imagen pesadas, codificación de video, criptografía e inferencia de ML bloquean el hilo de JS si se hacen en puro JavaScript. Los módulos nativos ejecutan trabajo en colas de fondo o rutas 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 es rápido para la lógica de aplicación - no es un sustituto para Core Image, MediaCodec o SIMD C++
• Perfila en el dispositivo: si los fotogramas de JS caen coincidiendo con tu función, mueve el trabajo a nativo o a un worker

8. Cuando las integraciones del sistema requieren puntos de entrada nativos

Las hojas de compartición, widgets de pantalla de inicio, App Clips y enlaces universales se registran en la capa de aplicación nativa. JavaScript recibe eventos de enlace profundo; el código nativo posee el 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();
}

// fragmento app.json - los dominios asociados son derechos nativos
{
  "expo": {
    "scheme": "myapp",
    "ios": {
      "associatedDomains": ["applinks:shop.example.com"]
    }
  }
}

• Los dominios asociados y los filtros de intents de Android se aplican durante el prebuild - exprésalos en la configuración, no ediciones manuales de Info.plist

9. Cuando Bluetooth / BLE necesita stacks GATT nativos

Bluetooth web no está disponible en React Native. El escaneo de BLE, emparejamiento y lectura/escritura de GATT requieren CoreBluetooth (iOS) y BluetoothGatt (Android):

// Conceptual - las librerías BLE reales exponen 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("Found", device.name);
  });
}

• Las librerías BLE nunca están en Expo Go - planifica expo-dev-client desde el primer día
• BLE en segundo plano en iOS requiere derechos adicionales y agota la batería - documenta en tu ADR

10. Cuando los polyfills de JS no pueden satisfacer los requisitos de tienda o seguridad

A veces la brecha no es capacidad sino cumplimiento: fijación de certificado, detección de jailbreak, SDKs de pago propios o APIs requeridas por MDM. Estos se envían como binarios nativos sin equivalente de Expo SDK:

// Fachada de capa de aplicación - la implementación es un módulo nativo o SDK de terceros
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();
}

• La revisión de tienda puede requerir versiones específicas de SDK nativos - los wrappers de JS deben coincidir con construcciones nativas fijadas
• Cada solución alternativa solo de polyfill que toque la seguridad debe ser rechazada en revisión de código - ver Reglas de Módulos Nativos

Cómo cargan los módulos nativos en SDK 57

JavaScript (Hermes)
    │
    ▼
expo-modules-core / JSI host object
    │
    ├── Expo Modules API (expo-camera, expo-file-system, …)
    ├── React Native TurboModules (community libraries)
    └── Legacy bridge fallback (older libraries only)
    │
    ▼
Swift / Kotlin / C++ native implementation

import { requireNativeModule, requireOptionalNativeModule } from "expo-modules-core";
 
// Lanza si falta clase nativa en binario
const FileSystem = requireNativeModule("ExpoFileSystem");
 
// Devuelve null en tests o cuando módulo no está enlazado
const Optional = requireOptionalNativeModule("ExpoCustomFeature");

Ver Expo Modules Core para detalles de bootstrap y Expo Go vs Development Builds para restricciones de tiempo de ejecución.

Errores comunes

• Esperar que Expo Go cargue cualquier paquete nativo npm - solo funcionan módulos preinstalados. Solución: npx expo install expo-dev-client y construir un cliente de desarrollo.
• Instalar con npm install en lugar de npx expo install - las versiones de JS y binarios nativos se desvían. Solución: siempre npx expo install <package> para deps nativos.
• Omitir reconstrucción nativa después del cambio de package.json - el recarga en caliente de Metro no compila Swift/Kotlin. Solución: npx expo run:ios / eas build después de cada cambio nativo.
• Llamar a módulos nativos a nivel superior del módulo en tests - Jest no tiene bridge. Solución: mockear en límite de servicio o usar jest-expo.
• Editar manualmente ios/ y android/ en aplicaciones CNG - el siguiente prebuild --clean borra ediciones. Solución: codifica cambios en plugins de configuración según CNG prebuild.

FAQs

Relacionado

• Usando Bibliotecas Nativas de Terceros - lista de compatibilidad
• Config Plugins - cambios de permisos y manifiesto
• create-expo-module - base de un módulo local
• Reglas de Módulos Nativos - lista de decisiones
• Fundamentos de Prebuild - generando proyectos nativos
• Expo Modules Core - internals del cargador JSI
• Expo Go vs Development Builds - límites de tiempo de ejecución
• Simulando Módulos Nativos - Jest sin un bridge

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