Expo Modules Core

El paquete expo es más que un fijador de versión - inicia Expo Modules Core, el runtime JSI-nativo que registra módulos de SDK de Expo, expone requireNativeModule, y conecta JavaScript con implementaciones en Swift/Kotlin en todas las aplicaciones Expo y bare React Native.

Receta

Card de referencia rápida - lista para copiar y pegar.

// index.ts (entrada personalizada) o App.tsx raíz
import { registerRootComponent } from "expo";
import { requireNativeModule, requireOptionalNativeModule } from "expo-modules-core";
import App from "./App";
 
// Opcional: sondea un módulo nativo al iniciar (diagnósticos de desarrollo)
const ExpoDevice = requireOptionalNativeModule("ExpoDevice");
if (__DEV__ && ExpoDevice) {
  console.log("Módulo nativo ExpoDevice cargado vía JSI");
}
 
registerRootComponent(App);

# Asegúrate de que el paquete central coincida con SDK 57
npx expo install expo expo-modules-core

Cuándo usar esto:

• Entender por qué import { Camera } from 'expo-camera' funciona después de solo npx expo install.
• Depurar Cannot find native module 'Expo…' en configuraciones bare o brownfield.
• Llamar a requireNativeModule desde bibliotecas compartidas sin componentes React.
• Escribir o integrar módulos nativos construidos con la API de Expo Modules.

Ejemplo funcional

// src/native/brightness.ts - envoltura tipada delgada sobre un módulo nativo Expo
import { requireNativeModule, NativeModule } from "expo-modules-core";
 
type BrightnessModule = NativeModule & {
  getBrightnessAsync: () => Promise<number>;
  setBrightnessAsync: (value: number) => Promise<void>;
};
 
const Brightness = requireNativeModule<BrightnessModule>("ExpoBrightness");
 
export async function dimToHalf(): Promise<number> {
  const current = await Brightness.getBrightnessAsync();
  await Brightness.setBrightnessAsync(0.5);
  return current;
}

// App.tsx - registro raíz + sondeo en tiempo de ejecución
import { useEffect, useState } from "react";
import { Button, StyleSheet, Text, View } from "react-native";
import { registerRootComponent } from "expo";
import * as Device from "expo-device";
import { dimToHalf } from "./src/native/brightness";
 
function App() {
  const [model, setModel] = useState<string>("…");
  const [restored, setRestored] = useState<string>("");
 
  useEffect(() => {
    setModel(Device.modelName ?? "desconocido");
  }, []);
 
  async function handleDim() {
    const previous = await dimToHalf();
    setRestored(`fue ${previous.toFixed(2)}`);
  }
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Expo Modules Core</Text>
      <Text>Dispositivo: {model}</Text>
      <Text>expo-device usa el mismo registro JSI que requireNativeModule</Text>
      <Button title="Oscurecer pantalla a 50%" onPress={handleDim} />
      {restored ? <Text>{restored}</Text> : null}
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 20, fontWeight: "700" },
});
 
registerRootComponent(App);

// android/app/src/main/java/.../MainActivity.java (bare) - nombre de componente requerido
@Override
protected String getMainComponentName() {
  return "main"; // coincide con registerRootComponent → AppRegistry.registerComponent("main", ...)
}

Lo que esto demuestra:

• registerRootComponent registra "main" con React Native y runtimes web.
• requireNativeModule carga el objeto host JSI exportado por Expo Modules Core.
• Los paquetes de alto nivel (expo-device) y requireNativeModule de bajo nivel comparten el mismo registro nativo.
• Los proyectos bare deben alinear moduleName en MainActivity / AppDelegate con "main".

Análisis profundo

Cómo funciona

Secuencia de arranque (lanzamiento de la aplicación)

1. La aplicación nativa comienza - ExpoModulesCore inicializa el objeto host JSI (global.expo.modules…).
2. El código nativo de cada módulo Expo instalado se registra (nombre - clase) durante el arranque nativo.
3. JavaScript carga - los polyfills de expo (registerRootComponent, globals web) se ejecutan.
4. Cuando JS llama a requireNativeModule("ExpoCamera"), Core busca el enlace JSI y devuelve un proxy NativeModule.
5. Si falta el enlace JSI (ruta heredada), Core retrocede a un proxy de bridge - algunas API síncronas pueden no estar disponibles.

Lanzamiento nativo
    │
    ▼
ExpoModulesCore (Swift / Kotlin / C++)
    │ registra ExpoCamera, ExpoDevice, …
    ▼
Se carga JS bundle (Metro)
    │
    ▼
requireNativeModule("ExpoCamera") ──JSI──▶ llamadas de método nativo

APIs clave de expo / expo-modules-core

import { EventEmitter, requireNativeModule } from "expo-modules-core";
 
// Los métodos de NativeModule son asíncronos por defecto a menos que se marquen como síncronos en código nativo
const module = requireNativeModule("ExpoFileSystem");

Relación con React Native New Architecture

• La API de Expo Modules se dirige a JSI y soporta TurboModules / Fabric en New Architecture.
• Compatible hacia atrás con arquitectura más antigua - existe fallback de proxy de bridge pero carece de características síncronas JSI.
• SDK 57 / RN 0.86 utilizan New Architecture por defecto; los módulos Expo se vinculan automáticamente a través de expo-modules-autolinking.

Disposición de paquetes en SDK 57

# Inspeccionar autolinking (depurar módulos faltantes)
npx expo-modules-autolinking resolve --platform ios

Requisitos de configuración Bare / Brownfield

Expo Modules Core se ejecuta en cualquier aplicación React Native que:

1. Dependa de expo y expo-modules-core (npx expo install expo expo-modules-core).
2. Aplique expo-modules-autolinking en settings.gradle / Podfile (agregado por npx install-expo-modules o Expo prebuild).
3. Registre el nombre del componente raíz JS main vía registerRootComponent.
4. Llame a configuración de entrada nativa en AppDelegate / MainApplication (las plantillas prebuild hacen esto automáticamente).

# Agregar módulos Expo a una aplicación bare RN existente
npx install-expo-modules@latest

Eventos de NativeModule

import { useEventListener } from "expo";
import { requireNativeModule } from "expo-modules-core";
 
const ExpoAccelerometer = requireNativeModule("ExpoAccelerometer");
 
export function AccelerometerListener() {
  useEventListener(ExpoAccelerometer, "accelerometerDidUpdate", (event) => {
    console.log(event.x, event.y, event.z);
  });
  return null;
}

EventEmitter en Core se implementa en C++ compartido entre plataformas - los listeners se disparan síncronamente en el hilo JS.

Notas de TypeScript

import type { NativeModule } from "expo-modules-core";
import { requireNativeModule } from "expo-modules-core";
 
interface ExpoHapticsModule extends NativeModule {
  impactAsync(style: "light" | "medium" | "heavy"): Promise<void>;
  selectionAsync(): Promise<void>;
}
 
export const Haptics = requireNativeModule<ExpoHapticsModule>("ExpoHaptics");

Escribir la interfaz documenta métodos nativos disponibles y detecta errores tipográficos en tiempo de compilación.

Errores comunes

• Nombre MainComponent incorrecto en aplicaciones bare - La entrada nativa aún dice "MyApp" mientras que JS registra "main". Solución: Establece getMainComponentName() / moduleName a "main" o coincide con tu nombre registerRootComponent.
• Autolinking faltante después de agregar expo-camera - La compilación nativa nunca compila el módulo. Solución: Ejecuta npx expo prebuild o verifica expo-modules-autolinking en Gradle/Podfile; reconstruye nativo.
• Llamar a requireNativeModule en Expo Go para módulos no empaquetados - Core funciona, pero la clase nativa nunca se envió en Expo Go. Solución: Development build con el módulo instalado.
• Asumir métodos síncronos de bridge en proxy de fallback - Cuando falta el enlace JSI, algunas API síncronas no funcionan o lanzan. Solución: Reconstruye con New Architecture habilitada; verifica que el módulo soporte funciones síncronas.
• Importar desde expo vs expo-modules-core - Los autores de aplicaciones pueden usar cualquiera para requireNativeModule; los paquetes de biblioteca deben importar desde expo-modules-core para evitar ciclos de peer-dep. Solución: Bibliotecas - expo-modules-core; aplicaciones - re-exportaciones de expo.
• Fugando SharedObjects - Los identificadores nativos duraderos (reproductores de video) retienen memoria hasta release() o limpieza de hook. Solución: Usa hooks de paquete (useVideoPlayer) o llama a release() cuando hayas terminado.
• Omitir npx expo install - Las versiones npm manuales desajustan binarios nativos vs stubs JS. Solución: Siempre npx expo install <pkg> para que autolinking resuelva compilaciones compatibles con SDK 57.

Alternativas

Preguntas frecuentes

npx expo-modules-autolinking resolve --platform android
npx expo-modules-autolinking resolve --platform ios

Relacionado

• Expo Platform Basics - dónde se sitúan Expo Modules en el flujo de trabajo gestionado
• Expo Go vs Development Builds - cuándo los módulos nativos están realmente en tu binario
• create-expo-app Quickstart - andamio de SDK 57 con módulos pre-cableados
• app.json & app.config.js - config plugins que los módulos nativos dependen
• Managed - Bare Migration - autolinking cuando expulsas a directorios nativos
• React Native Basics - hilo JS vs llamadas a módulos nativos

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