create-expo-module

Q: O create-expo-module funciona fora dos apps Expo?

Sim, em apps React Native puros com expo-modules-core instalado via npx install-expo-modules. O Expo prebuild ainda é o caminho de conexão mais fácil.

Q: Posso colocar o módulo dentro de packages/ em um monorepo?

Sim. Use workspace:* e ative autolinkingModuleResolution - veja a página de autolinking.

Q: Como adiciono eventos do nativo para o JS?

Use Events("onTrustChanged") em ModuleDefinition e EventEmitter no lado JS - o mesmo padrão de expo-sensors.

Q: Como publico o módulo no npm?

Complete a criação, adicione README e testes, execute npm publish de modules/device-trust. Os consumidores executam npx expo install device-trust e registram qualquer plugin.

Um guia para criar um módulo nativo local com uma interface TypeScript tipada - o caminho suportado quando os pacotes do Expo SDK e bibliotecas de terceiros não cobrem sua integração.

Receita

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

# Da raiz do seu app Expo
npx create-expo-module@latest modules/attestation
 
# Responda às perguntas: nome do módulo, descrição, plataformas (ios + android)
 
cd modules/attestation
npm install
npm run build   # compila a interface TypeScript
 
# Conecte ao app (dependência de workspace ou de arquivo)
cd ../..
npm install ./modules/attestation
 
# Gere os projetos nativos novamente
npx expo prebuild --clean
npx expo run:ios

// Uso do app após a criação
import AttestationModule from "attestation";
 
const result = await AttestationModule.isDeviceTrustedAsync();

Quando usar isso:

Conectar um SDK de fornecedor (detecção de fraude, scanner proprietário) com uma API nativa fina.
Expor uma ou duas APIs de plataforma não cobertas pelo Expo SDK (por exemplo, acesso personalizado ao Keychain).
Compartilhar código nativo entre vários aplicativos em um monorepo via packages/attestation.
Prototipagem antes de extrair um pacote npm publicável.

Exemplo de Trabalho

1. Crie o módulo

npx create-expo-app@latest AttestationApp --template blank-typescript@sdk-57 --yes
cd AttestationApp
npx create-expo-module@latest modules/device-trust

Layout de saída típico:

AttestationApp/
├── app.json
├── package.json
├── App.tsx
└── modules/
    └── device-trust/
        ├── android/
        │   └── src/main/java/expo/modules/devicetrust/DeviceTrustModule.kt
        ├── ios/
        │   └── DeviceTrustModule.swift
        ├── src/
        │   ├── DeviceTrustModule.ts
        │   └── index.ts
        ├── expo-module.config.json
        └── package.json

2. Implemente a interface nativa

// modules/device-trust/ios/DeviceTrustModule.swift
import ExpoModulesCore
 
public class DeviceTrustModule: Module {
  public func definition() -> ModuleDefinition {
    Name("DeviceTrust")
 
    AsyncFunction("isDeviceTrustedAsync") { () -> Bool in
      // Substitua pela integração DeviceCheck / App Attest
      #if targetEnvironment(simulator)
      return false
      #else
      return true
      #endif
    }
  }
}

// modules/device-trust/android/src/main/java/expo/modules/devicetrust/DeviceTrustModule.kt
package expo.modules.devicetrust
 
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
 
class DeviceTrustModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("DeviceTrust")
 
    AsyncFunction("isDeviceTrustedAsync") {
      // Substitua pela API Play Integrity
      !Build.FINGERPRINT.contains("generic")
    }
  }
}

// modules/device-trust/src/DeviceTrustModule.ts
import { requireNativeModule } from "expo-modules-core";
 
type DeviceTrustModuleType = {
  isDeviceTrustedAsync: () => Promise<boolean>;
};
 
export default requireNativeModule<DeviceTrustModuleType>("DeviceTrust");

// modules/device-trust/src/index.ts
export { default } from "./DeviceTrustModule";

3. Conecte ao app

// AttestationApp/package.json (trecho)
{
  "dependencies": {
    "device-trust": "file:./modules/device-trust",
    "expo": "~57.0.4",
    "expo-dev-client": "~6.0.0",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

// App.tsx
import { useEffect, useState } from "react";
import { Button, StyleSheet, Text, View } from "react-native";
import DeviceTrust from "device-trust";
 
export default function App() {
  const [trusted, setTrusted] = useState<boolean | null>(null);
 
  useEffect(() => {
    DeviceTrust.isDeviceTrustedAsync().then(setTrusted);
  }, []);
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Módulo Device Trust</Text>
      <Text>Confiável: {trusted === null ? "…" : trusted ? "sim" : "não"}</Text>
      <Button title="Verificar novamente" onPress={() => DeviceTrust.isDeviceTrustedAsync().then(setTrusted)} />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 20, fontWeight: "700" },
});

# Compile o TS do módulo, faça o prebuild, execute
cd modules/device-trust && npm run build && cd ../..
npx expo install expo-dev-client
npx expo prebuild
npx expo run:ios

O que isso demonstra:

create-expo-module gera esqueletos correspondentes de Swift/Kotlin/TypeScript com o registro correto de Name("DeviceTrust").
requireNativeModule carrega a ligação JSI após a compilação do código nativo por autolinking.
Dependência file:./modules/... mantém o módulo local - publique mais tarde se for reutilizado entre repositórios.
Build de desenvolvimento é necessário - código nativo personalizado nunca está no Expo Go.

4. Plugin de configuração opcional

Se o módulo precisar de entitlements, adicione app.plugin.js dentro do pacote do módulo e registre-o em app.config.ts do app. Veja Plugins de Configuração.

Mergulho Profundo

expo-module.config.json

{
  "platforms": ["ios", "android"],
  "ios": {
    "modules": ["DeviceTrustModule"]
  },
  "android": {
    "modules": ["expo.modules.devicetrust.DeviceTrustModule"]
  }
}

O autolinking lê este arquivo durante npx expo prebuild e conecta as entradas do Gradle/Pod - sem vinculação manual em apps CNG.

Posicionamento em Monorepo

Layout	Caminho	Dependência
App único	`modules/device-trust`	`"file:./modules/device-trust"`
Pacote Monorepo	`packages/device-trust`	`"workspace:*"` em `package.json` do app
npm publicado	registro externo	`"device-trust": "^1.0.0"`

Para nuances de autolinking em monorepos, veja Autolinking & expo-modules-core.

Módulo vs TurboModule

Módulo Expo (`create-expo-module`)	RN TurboModule (Codegen)
Autolinking Expo + plugins de configuração	RN-first; configuração manual do Codegen
DSL `ModuleDefinition` Swift/Kotlin	C++/Java/ObjC com arquivos de spec
Melhor para apps Expo SDK 57	Melhor para bibliotecas RN-core sem `expo`

A maioria das equipes de aplicativos deve começar com a API Expo Modules. Use Escrevendo um TurboModule ao compartilhar C++ entre plataformas ou fazer upstream para a comunidade RN.

Requisito de ADR

De acordo com as Regras de Módulos Nativos, documente:

Por que o Expo SDK e os pacotes de terceiros foram insuficientes
Mantenedor nomeado e cadência de revisão
Plano de teste da Nova Arquitetura
Propriedade do plugin de configuração para permissões

Armadilhas

Esquecer npm run build no módulo - o app importa a saída build/ desatualizada. Correção: Adicione "prepare": "expo-module build" ou compile em CI antes da compilação do app.
Discrepância entre Name("DeviceTrust") e requireNativeModule("DeviceTrust") - erro em tempo de execução. Correção: Mantenha os nomes idênticos entre Swift, Kotlin e TS.
Testando no Expo Go - código nativo do módulo personalizado não presente. Correção: Sempre use build de desenvolvimento.
Pular o prebuild após a criação do módulo - o projeto Xcode nunca referencia o módulo. Correção: npx expo prebuild --clean.
SDK nativo pesado no repositório do módulo - binários inchados e risco de licença. Correção: Módulo de ponte fina; versão do SDK do fornecedor fixada no ADR.

Alternativas

Alternativa	Use Quando	Não Use Quando
Pacote Expo SDK	O recurso existe upstream	API proprietária
Biblioteca nativa npm de terceiros	Ponte comunitária mantida	Não mantida ou sem Nova Arquitetura
Módulo Expo (esta página)	Ponte personalizada fina em app Expo	Núcleo compartilhado C++ pesado
TurboModule + Codegen	Biblioteca do ecossistema RN	Integração padrão de app CNG Expo

FAQs

O create-expo-module funciona fora dos apps Expo?

Sim, em apps React Native puros com expo-modules-core instalado via npx install-expo-modules. O Expo prebuild ainda é o caminho de conexão mais fácil.

Posso colocar o módulo dentro de packages/ em um monorepo?

Sim. Use workspace:* e ative autolinkingModuleResolution - veja a página de autolinking.

Como adiciono eventos do nativo para o JS?

Use Events("onTrustChanged") em ModuleDefinition e EventEmitter no lado JS - o mesmo padrão de expo-sensors.

Preciso de um plugin de configuração?

Somente quando o módulo requer permissões, entitlements, dependências Gradle ou metadados de manifesto não cobertos pelos padrões de autolinking.

Como publico o módulo no npm?

Complete a criação, adicione README e testes, execute npm publish de modules/device-trust. Os consumidores executam npx expo install device-trust e registram qualquer plugin.

Relacionados

Noções Básicas de Módulos Nativos - quando o código nativo é necessário
Plugins de Configuração - permissões para módulos personalizados
Autolinking & expo-modules-core - vinculação em monorepo
Escrevendo um TurboModule - alternativa Codegen
Regras de Módulos Nativos - ADR e checklist de nível
Código Nativo Personalizado em CNG - loops de execução e política de commit
Expo Modules Core - carregador em tempo de execução

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

Receita

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

# Da raiz do seu app Expo
npx create-expo-module@latest modules/attestation
 
# Responda às perguntas: nome do módulo, descrição, plataformas (ios + android)
 
cd modules/attestation
npm install
npm run build   # compila a interface TypeScript
 
# Conecte ao app (dependência de workspace ou de arquivo)
cd ../..
npm install ./modules/attestation
 
# Gere os projetos nativos novamente
npx expo prebuild --clean
npx expo run:ios

// Uso do app após a criação
import AttestationModule from "attestation";
 
const result = await AttestationModule.isDeviceTrustedAsync();

Quando usar isso:

Conectar um SDK de fornecedor (detecção de fraude, scanner proprietário) com uma API nativa fina.
Expor uma ou duas APIs de plataforma não cobertas pelo Expo SDK (por exemplo, acesso personalizado ao Keychain).
Compartilhar código nativo entre vários aplicativos em um monorepo via packages/attestation.
Prototipagem antes de extrair um pacote npm publicável.

Exemplo de Trabalho

1. Crie o módulo

npx create-expo-app@latest AttestationApp --template blank-typescript@sdk-57 --yes
cd AttestationApp
npx create-expo-module@latest modules/device-trust

Layout de saída típico:

AttestationApp/
├── app.json
├── package.json
├── App.tsx
└── modules/
    └── device-trust/
        ├── android/
        │   └── src/main/java/expo/modules/devicetrust/DeviceTrustModule.kt
        ├── ios/
        │   └── DeviceTrustModule.swift
        ├── src/
        │   ├── DeviceTrustModule.ts
        │   └── index.ts
        ├── expo-module.config.json
        └── package.json

2. Implemente a interface nativa

// modules/device-trust/ios/DeviceTrustModule.swift
import ExpoModulesCore
 
public class DeviceTrustModule: Module {
  public func definition() -> ModuleDefinition {
    Name("DeviceTrust")
 
    AsyncFunction("isDeviceTrustedAsync") { () -> Bool in
      // Substitua pela integração DeviceCheck / App Attest
      #if targetEnvironment(simulator)
      return false
      #else
      return true
      #endif
    }
  }
}

// modules/device-trust/android/src/main/java/expo/modules/devicetrust/DeviceTrustModule.kt
package expo.modules.devicetrust
 
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
 
class DeviceTrustModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("DeviceTrust")
 
    AsyncFunction("isDeviceTrustedAsync") {
      // Substitua pela API Play Integrity
      !Build.FINGERPRINT.contains("generic")
    }
  }
}

// modules/device-trust/src/DeviceTrustModule.ts
import { requireNativeModule } from "expo-modules-core";
 
type DeviceTrustModuleType = {
  isDeviceTrustedAsync: () => Promise<boolean>;
};
 
export default requireNativeModule<DeviceTrustModuleType>("DeviceTrust");

// modules/device-trust/src/index.ts
export { default } from "./DeviceTrustModule";

3. Conecte ao app

// AttestationApp/package.json (trecho)
{
  "dependencies": {
    "device-trust": "file:./modules/device-trust",
    "expo": "~57.0.4",
    "expo-dev-client": "~6.0.0",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

// App.tsx
import { useEffect, useState } from "react";
import { Button, StyleSheet, Text, View } from "react-native";
import DeviceTrust from "device-trust";
 
export default function App() {
  const [trusted, setTrusted] = useState<boolean | null>(null);
 
  useEffect(() => {
    DeviceTrust.isDeviceTrustedAsync().then(setTrusted);
  }, []);
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Módulo Device Trust</Text>
      <Text>Confiável: {trusted === null ? "…" : trusted ? "sim" : "não"}</Text>
      <Button title="Verificar novamente" onPress={() => DeviceTrust.isDeviceTrustedAsync().then(setTrusted)} />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 20, fontWeight: "700" },
});

# Compile o TS do módulo, faça o prebuild, execute
cd modules/device-trust && npm run build && cd ../..
npx expo install expo-dev-client
npx expo prebuild
npx expo run:ios

O que isso demonstra:

create-expo-module gera esqueletos correspondentes de Swift/Kotlin/TypeScript com o registro correto de Name("DeviceTrust").
requireNativeModule carrega a ligação JSI após a compilação do código nativo por autolinking.
Dependência file:./modules/... mantém o módulo local - publique mais tarde se for reutilizado entre repositórios.
Build de desenvolvimento é necessário - código nativo personalizado nunca está no Expo Go.

4. Plugin de configuração opcional

Se o módulo precisar de entitlements, adicione app.plugin.js dentro do pacote do módulo e registre-o em app.config.ts do app. Veja Plugins de Configuração.

Mergulho Profundo

expo-module.config.json

{
  "platforms": ["ios", "android"],
  "ios": {
    "modules": ["DeviceTrustModule"]
  },
  "android": {
    "modules": ["expo.modules.devicetrust.DeviceTrustModule"]
  }
}

O autolinking lê este arquivo durante npx expo prebuild e conecta as entradas do Gradle/Pod - sem vinculação manual em apps CNG.

Posicionamento em Monorepo

Layout	Caminho	Dependência
App único	`modules/device-trust`	`"file:./modules/device-trust"`
Pacote Monorepo	`packages/device-trust`	`"workspace:*"` em `package.json` do app
npm publicado	registro externo	`"device-trust": "^1.0.0"`

Para nuances de autolinking em monorepos, veja Autolinking & expo-modules-core.

Módulo vs TurboModule

Módulo Expo (`create-expo-module`)	RN TurboModule (Codegen)
Autolinking Expo + plugins de configuração	RN-first; configuração manual do Codegen
DSL `ModuleDefinition` Swift/Kotlin	C++/Java/ObjC com arquivos de spec
Melhor para apps Expo SDK 57	Melhor para bibliotecas RN-core sem `expo`

A maioria das equipes de aplicativos deve começar com a API Expo Modules. Use Escrevendo um TurboModule ao compartilhar C++ entre plataformas ou fazer upstream para a comunidade RN.

Requisito de ADR

De acordo com as Regras de Módulos Nativos, documente:

Por que o Expo SDK e os pacotes de terceiros foram insuficientes
Mantenedor nomeado e cadência de revisão
Plano de teste da Nova Arquitetura
Propriedade do plugin de configuração para permissões

Armadilhas

Esquecer npm run build no módulo - o app importa a saída build/ desatualizada. Correção: Adicione "prepare": "expo-module build" ou compile em CI antes da compilação do app.
Discrepância entre Name("DeviceTrust") e requireNativeModule("DeviceTrust") - erro em tempo de execução. Correção: Mantenha os nomes idênticos entre Swift, Kotlin e TS.
Testando no Expo Go - código nativo do módulo personalizado não presente. Correção: Sempre use build de desenvolvimento.
Pular o prebuild após a criação do módulo - o projeto Xcode nunca referencia o módulo. Correção: npx expo prebuild --clean.
SDK nativo pesado no repositório do módulo - binários inchados e risco de licença. Correção: Módulo de ponte fina; versão do SDK do fornecedor fixada no ADR.

Alternativas

Alternativa	Use Quando	Não Use Quando
Pacote Expo SDK	O recurso existe upstream	API proprietária
Biblioteca nativa npm de terceiros	Ponte comunitária mantida	Não mantida ou sem Nova Arquitetura
Módulo Expo (esta página)	Ponte personalizada fina em app Expo	Núcleo compartilhado C++ pesado
TurboModule + Codegen	Biblioteca do ecossistema RN	Integração padrão de app CNG Expo

FAQs

O create-expo-module funciona fora dos apps Expo?

Sim, em apps React Native puros com expo-modules-core instalado via npx install-expo-modules. O Expo prebuild ainda é o caminho de conexão mais fácil.

Posso colocar o módulo dentro de packages/ em um monorepo?

Sim. Use workspace:* e ative autolinkingModuleResolution - veja a página de autolinking.

Como adiciono eventos do nativo para o JS?

Use Events("onTrustChanged") em ModuleDefinition e EventEmitter no lado JS - o mesmo padrão de expo-sensors.

Preciso de um plugin de configuração?

Somente quando o módulo requer permissões, entitlements, dependências Gradle ou metadados de manifesto não cobertos pelos padrões de autolinking.

Como publico o módulo no npm?

Complete a criação, adicione README e testes, execute npm publish de modules/device-trust. Os consumidores executam npx expo install device-trust e registram qualquer plugin.

Relacionados

Noções Básicas de Módulos Nativos - quando o código nativo é necessário
Plugins de Configuração - permissões para módulos personalizados
Autolinking & expo-modules-core - vinculação em monorepo
Escrevendo um TurboModule - alternativa Codegen
Regras de Módulos Nativos - ADR e checklist de nível
Código Nativo Personalizado em CNG - loops de execução e política de commit
Expo Modules Core - carregador em tempo de execução

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

create-expo-module

Buscar na documentação

create-expo-module