Expo Modules Core

O pacote expo é mais do que um pino de versão - ele inicializa o Expo Modules Core, o runtime nativo JSI que registra os módulos do SDK Expo, expõe requireNativeModule e conecta JavaScript a implementações Swift/Kotlin em todos os apps Expo e React Native bare.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// index.ts (ponto de entrada customizado) ou root do App.tsx
import { registerRootComponent } from "expo";
import { requireNativeModule, requireOptionalNativeModule } from "expo-modules-core";
import App from "./App";
 
// Opcional: sonda um módulo nativo na inicialização (diagnóstico de dev)
const ExpoDevice = requireOptionalNativeModule("ExpoDevice");
if (__DEV__ && ExpoDevice) {
  console.log("Módulo nativo ExpoDevice carregado via JSI");
}
 
registerRootComponent(App);

# Garanta que o pacote core corresponda ao SDK 57
npx expo install expo expo-modules-core

Quando usar isso:

• Para entender por que import { Camera } from 'expo-camera' funciona após apenas npx expo install.
• Para depurar Cannot find native module 'Expo…' em configurações bare ou brownfield.
• Para chamar requireNativeModule de bibliotecas compartilhadas sem componentes React.
• Para criar ou integrar módulos nativos construídos com a Expo Modules API.

Exemplo de Trabalho

// src/native/brightness.ts - wrapper tipado leve sobre um 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 root + sonda de runtime
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 ?? "unknown");
  }, []);
 
  async function handleDim() {
    const previous = await dimToHalf();
    setRestored(`era ${previous.toFixed(2)}`);
  }
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Expo Modules Core</Text>
      <Text>Dispositivo: {model}</Text>
      <Text>expo-device usa o mesmo registro JSI que requireNativeModule</Text>
      <Button title="Diminuir tela para 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) - nome do componente principal necessário
@Override
protected String getMainComponentName() {
  return "main"; // corresponde a registerRootComponent → AppRegistry.registerComponent("main", ...)
}

O que isso demonstra:

• registerRootComponent registra "main" com os runtimes React Native e web.
• requireNativeModule carrega o objeto host JSI exportado pelo Expo Modules Core.
• Pacotes de alto nível (expo-device) e requireNativeModule de baixo nível compartilham o mesmo registro nativo.
• Projetos bare devem alinhar o moduleName de MainActivity / AppDelegate com "main".

Mergulho Profundo

Como Funciona

Sequência de inicialização (lançamento do app)

1. O app nativo inicia → ExpoModulesCore inicializa o objeto host JSI (global.expo.modules…).
2. O código nativo de cada módulo Expo instalado se registra (nome → classe) durante a inicialização nativa.
3. O JavaScript carrega → os polyfills do expo (registerRootComponent, globais web) são executados.
4. Quando o JS chama requireNativeModule("ExpoCamera"), o Core procura o binding JSI e retorna um proxy NativeModule.
5. Se o binding JSI estiver ausente (caminho legado), o Core recorre a um proxy de bridge - algumas APIs síncronas podem não estar disponíveis.

Inicialização Nativa
    │
    ▼
ExpoModulesCore (Swift / Kotlin / C++)
    │ registra ExpoCamera, ExpoDevice, …
    ▼
Bundle JS carrega (Metro)
    │
    ▼
requireNativeModule("ExpoCamera") ──JSI──▶ chamadas de método nativas

APIs Chave de expo / expo-modules-core

import { EventEmitter, requireNativeModule } from "expo-modules-core";
 
// Métodos NativeModule são assíncronos por padrão, a menos que marcados como síncronos no código nativo
const module = requireNativeModule("ExpoFileSystem");

Relação com a Nova Arquitetura do React Native

• A Expo Modules API visa o JSI e suporta TurboModules / Fabric na Nova Arquitetura.
• Retrocompatível com arquiteturas mais antigas - o fallback do proxy de bridge existe, mas carece de recursos JSI síncronos.
• SDK 57 / RN 0.86 usam a Nova Arquitetura por padrão; os módulos Expo se vinculam automaticamente através de expo-modules-autolinking.

Layout do Pacote no SDK 57

# Inspeção de Autolinking (depurar módulos ausentes)
npx expo-modules-autolinking resolve --platform ios

Requisitos de Configuração Bare / Brownfield

O Expo Modules Core roda em qualquer app React Native que:

1. Depende de expo e expo-modules-core (npx expo install expo expo-modules-core).
2. Aplica expo-modules-autolinking em settings.gradle / Podfile (adicionado por npx install-expo-modules ou Expo prebuild).
3. Registra o nome do componente root JS main via registerRootComponent.
4. Chama a configuração de entrada nativa em AppDelegate / MainApplication (templates prebuild fazem isso automaticamente).

# Adicionar módulos Expo a um app bare RN existente
npx install-expo-modules@latest

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

O EventEmitter no Core é implementado em C++ compartilhado entre plataformas - os listeners disparam síncronamente na thread JS.

Notas 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");

Tipar a interface documenta os métodos nativos disponíveis e pega erros de digitação em tempo de compilação.

Armadilhas

• Nome incorreto de MainComponent em apps bare - A entrada nativa ainda diz "MyApp" enquanto o JS registra "main". Correção: Defina getMainComponentName() / moduleName para "main" ou o nome do seu registerRootComponent.
• Autolinking ausente após adicionar expo-camera - O build nativo nunca compilou o módulo. Correção: Execute npx expo prebuild ou verifique expo-modules-autolinking no Gradle/Podfile; reconstrua o nativo.
• Chamar requireNativeModule no Expo Go para módulos não empacotados - O Core funciona, mas a classe nativa nunca foi incluída no Expo Go. Correção: Build de desenvolvimento com o módulo instalado.
• Assumir métodos síncronos de bridge no proxy de fallback - Quando o binding JSI está ausente, algumas APIs síncronas não fazem nada ou lançam erro. Correção: Reconstrua com a Nova Arquitetura habilitada; verifique se o módulo suporta funções síncronas.
• Importar de expo vs expo-modules-core - Autores de apps podem usar qualquer um para requireNativeModule; pacotes de bibliotecas devem importar de expo-modules-core para evitar ciclos de dependência entre pares. Correção: Bibliotecas → expo-modules-core; apps → expo re-exports.
• Vazamento de SharedObjects - Handles nativos de longa duração (players de vídeo) retêm memória até release() ou limpeza de hook. Correção: Use hooks do pacote (useVideoPlayer) ou chame release() quando terminar.
• Pular npx expo install - Versões npm manuais não correspondem aos binários nativos vs stubs JS. Correção: Sempre use npx expo install <pkg> para que o autolinking resolva builds compatíveis com SDK 57.

Alternativas

FAQs

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

Relacionados

• Noções Básicas da Plataforma Expo - onde o Expo Modules se encaixa no fluxo gerenciado
• Expo Go vs Builds de Desenvolvimento - quando os módulos nativos estão realmente em seu binário
• create-expo-app Quickstart - scaffold do SDK 57 com módulos pré-configurados
• app.json & app.config.js - plugins de configuração dos quais os módulos nativos dependem
• Migração Gerenciado → Bare - autolinking quando você ejeta para diretórios nativos
• Noções Básicas do React Native - thread JS vs chamadas de módulo nativo

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