Noções Básicas do Expo SDK

Q: Posso usar npm install em vez de npx expo install?

npm install simples ignora a tabela de compatibilidade do SDK - use-o apenas para pacotes não Expo (zod, @tanstack/react-query). Para qualquer pacote expo-*, sempre use npx expo install .

Q: Preciso reconstruir após adicionar um pacote Expo apenas JS?

Se o pacote não tiver código nativo e nenhum plugin de configuração, uma reinicialização do Metro é suficiente. Se ele adicionar código nativo ou um plugin, execute npx expo prebuild ou um novo build EAS.

10 exemplos para você começar com pacotes do Expo SDK - 7 básicos e 3 intermediários. Cobre a instalação com npx expo install, versionamento do SDK e como os módulos nativos inicializam dentro do seu app.

Pré-requisitos

Crie um app Expo com SDK 57 antes de adicionar pacotes do SDK:

npx create-expo-app@latest SdkBasics --template blank-typescript
cd SdkBasics

Confirme o pin do SDK:

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Exemplos Básicos

1. O que são Pacotes do Expo SDK

Pacotes do Expo SDK são módulos nativos com uma API JavaScript - câmera, sistema de arquivos, notificações e dezenas de outros são distribuídos como pacotes npm versionados contra uma única versão do expo.

import { StatusBar } from "expo-status-bar";
import { StyleSheet, Text, View } from "react-native";
 
export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Pacotes do Expo SDK</Text>
      <Text style={styles.body}>
        Importações JavaScript chamam código nativo compilado para SDK 57 - não
        polyfills de navegador.
      </Text>
      <StatusBar style="auto" />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 22, fontWeight: "700" },
  body: { fontSize: 15, color: "#4b5563", lineHeight: 22 },
});

Cada pacote (expo-camera, expo-location, …) é um módulo Expo com implementações iOS e Android
O pacote expo é a raiz do SDK - sua versão define quais versões de módulos são compatíveis
Pacotes funcionam no Expo Go quando listados no cliente Go; código nativo personalizado requer um build de desenvolvimento
Prefira módulos Expo curados em vez de forks da comunidade não mantidos quando ambos cobrem a mesma funcionalidade

Relacionado: ../expo-platform/expo-platform-basics/expo-platform-basics.md - visão geral da camada de plataforma | ../expo-platform/expo-modules-core/expo-modules-core.md - bootstrap nativo

2. Instale Pacotes com npx expo install

Sempre adicione módulos Expo através da CLI para que os intervalos semver correspondam à matriz de compatibilidade do SDK.

# Um ou mais pacotes - versões resolvidas para SDK 57
npx expo install expo-notifications expo-location
 
# Após edições manuais de package.json ou um bump de SDK
npx expo install --fix
 
# Verifique se não há descompasso de versão antes do seu primeiro build nativo
npx expo doctor

{
  "dependencies": {
    "expo": "~57.0.4",
    "expo-notifications": "~0.32.0",
    "expo-location": "~19.0.0"
  }
}

npx expo install lê sua versão do expo e escolhe intervalos testados - npm install expo-camera@latest pode puxar código nativo incompatível com o SDK
--fix reconcilia cada dependência Expo após atualizar o expo em package.json
expo doctor sinaliza cópias duplicadas do React Native, versões incorretas de módulos e plugins de configuração ausentes
Commite package-lock.json / yarn.lock para que o CI instale o mesmo ABI nativo que seu laptop construiu

Relacionado: ./expo-notifications.md - instalação da primeira notificação push | ./expo-location.md - permissões de localização

3. Versão do SDK como Contrato

O campo expo em package.json é a única fonte de verdade que todos os outros pacotes Expo devem satisfazer.

Contrato do SDK 57
 
expo ~57.0.4          ← pin raiz do SDK
├── react 19.2.3      ← pareado por create-expo-app
├── react-native 0.86.0
├── expo-camera ~17.x ← resolvido por expo install
├── expo-file-system ~19.x
└── …                 ← todos os módulos validados contra a matriz SDK 57

# Bump de SDK intencional - leia o changelog primeiro
npx expo install expo@~57.0.4
npx expo install --fix
npx expo prebuild --clean   # quando as pastas nativas existem

Misturar módulos do SDK 56 com expo do SDK 57 causa erros de compilação nativa - a matriz não é consultiva
~57.0.4 permite lançamentos de patch dentro do SDK 57 - fixe intencionalmente para CI reproduzível
Após um bump, execute --fix antes de depurar crashes em tempo de execução - o descompasso de versão frequentemente se manifesta como exceções nativas obscuras
Pastas nativas (ios/, android/) devem ser regeneradas ou reconstruídas após saltos de SDK

Relacionado: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md - runbook de atualização

4. Importe e Use um Módulo

Módulos Expo exportam um namespace ou classes nomeadas - importe uma vez, chame APIs assíncronas de efeitos ou manipuladores.

npx expo install expo-haptics

import * as Haptics from "expo-haptics";
import { Pressable, StyleSheet, Text, View } from "react-native";
 
export default function App() {
  return (
    <View style={styles.container}>
      <Pressable
        style={styles.button}
        onPress={() => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)}
      >
        <Text style={styles.label}>Toque para feedback háptico</Text>
      </Pressable>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", alignItems: "center" },
  button: { backgroundColor: "#2563eb", paddingHorizontal: 20, paddingVertical: 12, borderRadius: 10 },
  label: { color: "#fff", fontWeight: "600" },
});

A maioria das APIs são assíncronas - permissões, acesso a hardware e I/O retornam Promises
Tipos TypeScript vêm com o pacote - nenhum pacote @types/ é necessário para módulos Expo de primeira parte
Teste em um dispositivo físico quando a API tocar em sensores, push ou execução em segundo plano
Envolva chamadas em try/catch - negações de permissão e ausência de hardware lançam ou retornam erros estruturados

Relacionado: ../rn-fundamentals/platform-specific-code/platform-specific-code.md - guardas Platform.OS

5. Permissões em app.config

Muitos pacotes do SDK requerem entradas de manifesto - declare-as em app.json ou app.config.ts antes de solicitar permissão em tempo de execução.

npx expo install expo-camera expo-location

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
export default (): ExpoConfig => ({
  name: "SdkBasics",
  slug: "sdk-basics",
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission:
          "Permitir que SdkBasics tire fotos para anexos de ordens de serviço.",
        microphonePermission:
          "Permitir que SdkBasics grave áudio com inspeções de vídeo.",
      },
    ],
    [
      "expo-location",
      {
        locationAlwaysAndWhenInUsePermission:
          "SdkBasics usa sua localização para marcar visitas de campo mesmo quando o app está em segundo plano.",
        locationWhenInUsePermission:
          "SdkBasics usa sua localização para mostrar locais de trabalho próximos.",
      },
    ],
  ],
});

Strings de plugin de configuração se tornam descrições de uso do Info.plist do iOS e justificativas de permissão do Android - App Review rejeita cópias vagas
Plugins são executados no prebuild - alterá-los requer um novo binário nativo, não apenas uma atualização OTA de JS
Solicite permissão em tempo de execução após explicar o valor na UI - veja ./best-practices.md
Emparelhe a cópia do manifesto com telas de pré-prompt no app antes de requestPermissionsAsync

Relacionado: ./expo-camera-and-expo-image-picker.md - permissões de captura | ./expo-location.md - strings de divulgação

6. Expo Go vs Build de Desenvolvimento

Expo Go agrupa um conjunto fixo de módulos nativos. Pacotes com código nativo personalizado ou plugins não publicados precisam de um cliente de desenvolvimento.

npx expo install expo-dev-client
npx expo run:ios
# ou cliente de desenvolvimento na nuvem:
npx eas build --profile development --platform ios

┌────────────────────┬─────────────────────┬──────────────────────────┐
│ Capacidade         │ Expo Go             │ Build de desenvolvimento │
├────────────────────┼─────────────────────┼──────────────────────────┤
│ expo-notifications │ Configuração push limitada │ Push completo + ícones personalizados │
│ expo-camera        │ Sim                 │ Sim + plugins personalizados │
│ Plugins de config  │ Ignorados           │ Aplicados no prebuild    │
│ expo-updates       │ Limitado            │ Canal OTA de produção    │
└────────────────────┴─────────────────────┴──────────────────────────┘

Expo Go é o mais rápido para aprendizado e trabalho de UI - não para QA final de push, localização em segundo plano ou OTA
expo-dev-client substitui o Go como o shell nativo, mantendo o Metro com fast refresh
Se npx expo start abrir o Go, mas seu recurso precisar de um plugin, instale o dev-client antes de depurar erros nativos de "módulo não encontrado"
A submissão para lojas sempre usa um build EAS ou binário de lançamento local - nunca o Expo Go

Relacionado: ../expo-platform/expo-go-vs-development-builds/expo-go-vs-development-builds.md - matriz de recursos

7. Ciclo de Vida do Módulo e Entrada do App

Alguns módulos requerem registro antes que o React monte - tarefas em segundo plano, manipuladores de notificação e ouvintes de atualização pertencem ao escopo global.

npx expo install expo-notifications expo-task-manager

// index.ts - importações de efeito colateral ANTES de registerRootComponent
import "./src/notifications/notificationHandler";
import "./src/background/locationTask";
import { registerRootComponent } from "expo";
import App from "./App";
 
registerRootComponent(App);

// src/notifications/notificationHandler.ts
import * as Notifications from "expo-notifications";
 
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

TaskManager.defineTask deve ser executado no escopo global - definir dentro de um componente falha na inicialização fria pelo sistema operacional
Manipuladores de notificação definidos antes que a primeira notificação chegue - importe o módulo na entrada
Apps Expo Router usam importações de nível superior em app/_layout.tsx para os mesmos efeitos colaterais
Mantenha os efeitos colaterais de entrada pequenos - trabalho pesado ainda pertence a módulos carregados preguiçosamente

Relacionado: ./expo-task-manager-and-background-tasks.md - registro global de tarefas | ./expo-notifications.md - manipulador em primeiro plano

Exemplos Intermediários

8. Autolinking e Geração de Projetos Nativos

O autolinking do Expo descobre módulos nativos do package.json e os conecta aos projetos ios/ e android/ gerados.

npx expo prebuild
# inspecione projetos nativos sem abrir o Xcode
ls ios/Pods 2>/dev/null || ls android/app/build.gradle

{
  "expo": {
    "plugins": ["expo-notifications"]
  }
}

npx expo prebuild gera pastas nativas a partir de app.config + módulos instalados - CNG os mantém fora do git no fluxo de trabalho gerenciado
Autolinking lê expo-module.config.json em cada pacote - edições manuais de pod install são sobrescritas na próxima prebuild
Adicionar um pacote com um plugin de configuração altera projetos nativos - comite a configuração, não Info.plist editado manualmente, ao usar CNG
Times no fluxo de trabalho bare ainda executam npx expo install para segurança de versão - o autolinking funciona da mesma forma

Relacionado: ../cng-prebuild/prebuild-basics/prebuild-basics.md - quando fazer prebuild | ../native-modules/native-modules-basics/native-modules-basics.md - arquitetura de módulos

9. APIs Legadas vs Modernas Dentro de um Pacote

Alguns pacotes do SDK fornecem tanto uma API moderna quanto uma entrada /legacy - migre deliberadamente, não em um único PR.

npx expo install expo-file-system

// API moderna do SDK 57 - File, Directory, Paths
import { Directory, File, Paths } from "expo-file-system";
 
const cacheDir = new Directory(Paths.cache, "downloads");
cacheDir.create();
const meta = new File(cacheDir, "manifest.json");
meta.create();
meta.write(JSON.stringify({ version: 1 }));
 
// API Legada - ainda disponível durante a migração
import * as FileSystem from "expo-file-system/legacy";
 
const legacyUri = meta.uri;
const text = await FileSystem.readAsStringAsync(legacyUri);

Prefira File / Directory / Paths para código novo no SDK 57 - caminhos orientados a objetos reduzem bugs de strings de URI
Importe expo-file-system/legacy apenas para locais de chamada não migrados - planeje a remoção por lançamento
Leia o changelog de cada pacote no bump de SDK - renomeações e depreciações são por módulo, não apenas nas notas de lançamento do expo
Veja ./expo-file-system.md para caminhos de sandbox e padrões de download

Relacionado: ./expo-file-system.md - caminhos e downloads sandbox

10. Comportamento de Pacote Específico do Ambiente

Use app.config.ts e ambientes EAS para variar permissões, plugins e chaves de API - não forks if (__DEV__) em caminhos de produção.

// app.config.ts
const IS_DEV = process.env.APP_VARIANT === "development";
 
export default {
  name: IS_DEV ? "SdkBasics (Dev)" : "SdkBasics",
  slug: "sdk-basics",
  extra: {
    eas: { projectId: process.env.EAS_PROJECT_ID },
    pushEnabled: !IS_DEV,
  },
  plugins: [
    ...(IS_DEV ? [] : [["expo-notifications", { icon: "./assets/notification-icon.png" }]]),
  ],
};

import Constants from "expo-constants";
 
const pushEnabled = Constants.expoConfig?.extra?.pushEnabled ?? false;

extra está disponível em tempo de execução via expo-constants - adequado para flags de recursos resolvidos em tempo de compilação
EXPO_PUBLIC_* é incorporado ao JS - nunca coloque segredos lá; URLs de API apenas quando intencionalmente públicas
Desative plugins de push em dev ao testar sem credenciais APNs/FCM - reduz o atrito de configuração nativa
Alinhe variantes com ../expo-platform/environments-and-eas-environment-variables/environments-and-eas-environment-variables.md

Relacionado: ../expo-platform/app-json-and-app-config-js/app-json-and-app-config-js.md - configuração dinâmica

FAQs

Posso usar npm install em vez de npx expo install?

npm install simples ignora a tabela de compatibilidade do SDK - use-o apenas para pacotes não Expo (zod, @tanstack/react-query).
Para qualquer pacote expo-*, sempre use npx expo install <package>.

Como sei se um pacote funciona no Expo Go?

Verifique o cabeçalho da documentação do pacote - "Incluído no Expo Go" significa que o módulo é distribuído no cliente Go para seu SDK.
Plugins de configuração e código nativo personalizado requerem um build de desenvolvimento de qualquer maneira.

Preciso reconstruir após adicionar um pacote Expo apenas JS?

Se o pacote não tiver código nativo e nenhum plugin de configuração, uma reinicialização do Metro é suficiente.
Se ele adicionar código nativo ou um plugin, execute npx expo prebuild ou um novo build EAS.

Onde encontro versões compatíveis?

npx expo install expo-camera
npx expo doctor

A referência do Expo SDK lista cada versão de módulo para o SDK 57.

Relacionado

expo-notifications - notificações push e locais
expo-location - localização em primeiro plano e em segundo plano
expo-file-system - armazenamento do dispositivo
expo-secure-store & expo-crypto - segredos e hashing
../expo-platform/expo-platform-basics/expo-platform-basics.md - fundamentos da plataforma
Boas Práticas de Pacotes do Expo SDK - resumo da seçã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).

Pré-requisitos

Crie um app Expo com SDK 57 antes de adicionar pacotes do SDK:

npx create-expo-app@latest SdkBasics --template blank-typescript
cd SdkBasics

Confirme o pin do SDK:

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Exemplos Básicos

1. O que são Pacotes do Expo SDK

import { StatusBar } from "expo-status-bar";
import { StyleSheet, Text, View } from "react-native";
 
export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Pacotes do Expo SDK</Text>
      <Text style={styles.body}>
        Importações JavaScript chamam código nativo compilado para SDK 57 - não
        polyfills de navegador.
      </Text>
      <StatusBar style="auto" />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 22, fontWeight: "700" },
  body: { fontSize: 15, color: "#4b5563", lineHeight: 22 },
});

Cada pacote (expo-camera, expo-location, …) é um módulo Expo com implementações iOS e Android
O pacote expo é a raiz do SDK - sua versão define quais versões de módulos são compatíveis
Pacotes funcionam no Expo Go quando listados no cliente Go; código nativo personalizado requer um build de desenvolvimento
Prefira módulos Expo curados em vez de forks da comunidade não mantidos quando ambos cobrem a mesma funcionalidade

Relacionado: ../expo-platform/expo-platform-basics/expo-platform-basics.md - visão geral da camada de plataforma | ../expo-platform/expo-modules-core/expo-modules-core.md - bootstrap nativo

2. Instale Pacotes com npx expo install

Sempre adicione módulos Expo através da CLI para que os intervalos semver correspondam à matriz de compatibilidade do SDK.

# Um ou mais pacotes - versões resolvidas para SDK 57
npx expo install expo-notifications expo-location
 
# Após edições manuais de package.json ou um bump de SDK
npx expo install --fix
 
# Verifique se não há descompasso de versão antes do seu primeiro build nativo
npx expo doctor

{
  "dependencies": {
    "expo": "~57.0.4",
    "expo-notifications": "~0.32.0",
    "expo-location": "~19.0.0"
  }
}

npx expo install lê sua versão do expo e escolhe intervalos testados - npm install expo-camera@latest pode puxar código nativo incompatível com o SDK
--fix reconcilia cada dependência Expo após atualizar o expo em package.json
expo doctor sinaliza cópias duplicadas do React Native, versões incorretas de módulos e plugins de configuração ausentes
Commite package-lock.json / yarn.lock para que o CI instale o mesmo ABI nativo que seu laptop construiu

Relacionado: ./expo-notifications.md - instalação da primeira notificação push | ./expo-location.md - permissões de localização

3. Versão do SDK como Contrato

O campo expo em package.json é a única fonte de verdade que todos os outros pacotes Expo devem satisfazer.

Contrato do SDK 57
 
expo ~57.0.4          ← pin raiz do SDK
├── react 19.2.3      ← pareado por create-expo-app
├── react-native 0.86.0
├── expo-camera ~17.x ← resolvido por expo install
├── expo-file-system ~19.x
└── …                 ← todos os módulos validados contra a matriz SDK 57

# Bump de SDK intencional - leia o changelog primeiro
npx expo install expo@~57.0.4
npx expo install --fix
npx expo prebuild --clean   # quando as pastas nativas existem

Misturar módulos do SDK 56 com expo do SDK 57 causa erros de compilação nativa - a matriz não é consultiva
~57.0.4 permite lançamentos de patch dentro do SDK 57 - fixe intencionalmente para CI reproduzível
Após um bump, execute --fix antes de depurar crashes em tempo de execução - o descompasso de versão frequentemente se manifesta como exceções nativas obscuras
Pastas nativas (ios/, android/) devem ser regeneradas ou reconstruídas após saltos de SDK

Relacionado: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md - runbook de atualização

4. Importe e Use um Módulo

Módulos Expo exportam um namespace ou classes nomeadas - importe uma vez, chame APIs assíncronas de efeitos ou manipuladores.

npx expo install expo-haptics

import * as Haptics from "expo-haptics";
import { Pressable, StyleSheet, Text, View } from "react-native";
 
export default function App() {
  return (
    <View style={styles.container}>
      <Pressable
        style={styles.button}
        onPress={() => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)}
      >
        <Text style={styles.label}>Toque para feedback háptico</Text>
      </Pressable>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", alignItems: "center" },
  button: { backgroundColor: "#2563eb", paddingHorizontal: 20, paddingVertical: 12, borderRadius: 10 },
  label: { color: "#fff", fontWeight: "600" },
});

A maioria das APIs são assíncronas - permissões, acesso a hardware e I/O retornam Promises
Tipos TypeScript vêm com o pacote - nenhum pacote @types/ é necessário para módulos Expo de primeira parte
Teste em um dispositivo físico quando a API tocar em sensores, push ou execução em segundo plano
Envolva chamadas em try/catch - negações de permissão e ausência de hardware lançam ou retornam erros estruturados

Relacionado: ../rn-fundamentals/platform-specific-code/platform-specific-code.md - guardas Platform.OS

5. Permissões em app.config

Muitos pacotes do SDK requerem entradas de manifesto - declare-as em app.json ou app.config.ts antes de solicitar permissão em tempo de execução.

npx expo install expo-camera expo-location

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
export default (): ExpoConfig => ({
  name: "SdkBasics",
  slug: "sdk-basics",
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission:
          "Permitir que SdkBasics tire fotos para anexos de ordens de serviço.",
        microphonePermission:
          "Permitir que SdkBasics grave áudio com inspeções de vídeo.",
      },
    ],
    [
      "expo-location",
      {
        locationAlwaysAndWhenInUsePermission:
          "SdkBasics usa sua localização para marcar visitas de campo mesmo quando o app está em segundo plano.",
        locationWhenInUsePermission:
          "SdkBasics usa sua localização para mostrar locais de trabalho próximos.",
      },
    ],
  ],
});

Strings de plugin de configuração se tornam descrições de uso do Info.plist do iOS e justificativas de permissão do Android - App Review rejeita cópias vagas
Plugins são executados no prebuild - alterá-los requer um novo binário nativo, não apenas uma atualização OTA de JS
Solicite permissão em tempo de execução após explicar o valor na UI - veja ./best-practices.md
Emparelhe a cópia do manifesto com telas de pré-prompt no app antes de requestPermissionsAsync

Relacionado: ./expo-camera-and-expo-image-picker.md - permissões de captura | ./expo-location.md - strings de divulgação

6. Expo Go vs Build de Desenvolvimento

Expo Go agrupa um conjunto fixo de módulos nativos. Pacotes com código nativo personalizado ou plugins não publicados precisam de um cliente de desenvolvimento.

npx expo install expo-dev-client
npx expo run:ios
# ou cliente de desenvolvimento na nuvem:
npx eas build --profile development --platform ios

┌────────────────────┬─────────────────────┬──────────────────────────┐
│ Capacidade         │ Expo Go             │ Build de desenvolvimento │
├────────────────────┼─────────────────────┼──────────────────────────┤
│ expo-notifications │ Configuração push limitada │ Push completo + ícones personalizados │
│ expo-camera        │ Sim                 │ Sim + plugins personalizados │
│ Plugins de config  │ Ignorados           │ Aplicados no prebuild    │
│ expo-updates       │ Limitado            │ Canal OTA de produção    │
└────────────────────┴─────────────────────┴──────────────────────────┘

Expo Go é o mais rápido para aprendizado e trabalho de UI - não para QA final de push, localização em segundo plano ou OTA
expo-dev-client substitui o Go como o shell nativo, mantendo o Metro com fast refresh
Se npx expo start abrir o Go, mas seu recurso precisar de um plugin, instale o dev-client antes de depurar erros nativos de "módulo não encontrado"
A submissão para lojas sempre usa um build EAS ou binário de lançamento local - nunca o Expo Go

Relacionado: ../expo-platform/expo-go-vs-development-builds/expo-go-vs-development-builds.md - matriz de recursos

7. Ciclo de Vida do Módulo e Entrada do App

Alguns módulos requerem registro antes que o React monte - tarefas em segundo plano, manipuladores de notificação e ouvintes de atualização pertencem ao escopo global.

npx expo install expo-notifications expo-task-manager

// index.ts - importações de efeito colateral ANTES de registerRootComponent
import "./src/notifications/notificationHandler";
import "./src/background/locationTask";
import { registerRootComponent } from "expo";
import App from "./App";
 
registerRootComponent(App);

// src/notifications/notificationHandler.ts
import * as Notifications from "expo-notifications";
 
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

TaskManager.defineTask deve ser executado no escopo global - definir dentro de um componente falha na inicialização fria pelo sistema operacional
Manipuladores de notificação definidos antes que a primeira notificação chegue - importe o módulo na entrada
Apps Expo Router usam importações de nível superior em app/_layout.tsx para os mesmos efeitos colaterais
Mantenha os efeitos colaterais de entrada pequenos - trabalho pesado ainda pertence a módulos carregados preguiçosamente

Relacionado: ./expo-task-manager-and-background-tasks.md - registro global de tarefas | ./expo-notifications.md - manipulador em primeiro plano

Exemplos Intermediários

8. Autolinking e Geração de Projetos Nativos

O autolinking do Expo descobre módulos nativos do package.json e os conecta aos projetos ios/ e android/ gerados.

npx expo prebuild
# inspecione projetos nativos sem abrir o Xcode
ls ios/Pods 2>/dev/null || ls android/app/build.gradle

{
  "expo": {
    "plugins": ["expo-notifications"]
  }
}

npx expo prebuild gera pastas nativas a partir de app.config + módulos instalados - CNG os mantém fora do git no fluxo de trabalho gerenciado
Autolinking lê expo-module.config.json em cada pacote - edições manuais de pod install são sobrescritas na próxima prebuild
Adicionar um pacote com um plugin de configuração altera projetos nativos - comite a configuração, não Info.plist editado manualmente, ao usar CNG
Times no fluxo de trabalho bare ainda executam npx expo install para segurança de versão - o autolinking funciona da mesma forma

Relacionado: ../cng-prebuild/prebuild-basics/prebuild-basics.md - quando fazer prebuild | ../native-modules/native-modules-basics/native-modules-basics.md - arquitetura de módulos

9. APIs Legadas vs Modernas Dentro de um Pacote

Alguns pacotes do SDK fornecem tanto uma API moderna quanto uma entrada /legacy - migre deliberadamente, não em um único PR.

npx expo install expo-file-system

// API moderna do SDK 57 - File, Directory, Paths
import { Directory, File, Paths } from "expo-file-system";
 
const cacheDir = new Directory(Paths.cache, "downloads");
cacheDir.create();
const meta = new File(cacheDir, "manifest.json");
meta.create();
meta.write(JSON.stringify({ version: 1 }));
 
// API Legada - ainda disponível durante a migração
import * as FileSystem from "expo-file-system/legacy";
 
const legacyUri = meta.uri;
const text = await FileSystem.readAsStringAsync(legacyUri);

Prefira File / Directory / Paths para código novo no SDK 57 - caminhos orientados a objetos reduzem bugs de strings de URI
Importe expo-file-system/legacy apenas para locais de chamada não migrados - planeje a remoção por lançamento
Leia o changelog de cada pacote no bump de SDK - renomeações e depreciações são por módulo, não apenas nas notas de lançamento do expo
Veja ./expo-file-system.md para caminhos de sandbox e padrões de download

Relacionado: ./expo-file-system.md - caminhos e downloads sandbox

10. Comportamento de Pacote Específico do Ambiente

Use app.config.ts e ambientes EAS para variar permissões, plugins e chaves de API - não forks if (__DEV__) em caminhos de produção.

// app.config.ts
const IS_DEV = process.env.APP_VARIANT === "development";
 
export default {
  name: IS_DEV ? "SdkBasics (Dev)" : "SdkBasics",
  slug: "sdk-basics",
  extra: {
    eas: { projectId: process.env.EAS_PROJECT_ID },
    pushEnabled: !IS_DEV,
  },
  plugins: [
    ...(IS_DEV ? [] : [["expo-notifications", { icon: "./assets/notification-icon.png" }]]),
  ],
};

import Constants from "expo-constants";
 
const pushEnabled = Constants.expoConfig?.extra?.pushEnabled ?? false;

extra está disponível em tempo de execução via expo-constants - adequado para flags de recursos resolvidos em tempo de compilação
EXPO_PUBLIC_* é incorporado ao JS - nunca coloque segredos lá; URLs de API apenas quando intencionalmente públicas
Desative plugins de push em dev ao testar sem credenciais APNs/FCM - reduz o atrito de configuração nativa
Alinhe variantes com ../expo-platform/environments-and-eas-environment-variables/environments-and-eas-environment-variables.md

Relacionado: ../expo-platform/app-json-and-app-config-js/app-json-and-app-config-js.md - configuração dinâmica

FAQs

Posso usar npm install em vez de npx expo install?

npm install simples ignora a tabela de compatibilidade do SDK - use-o apenas para pacotes não Expo (zod, @tanstack/react-query).
Para qualquer pacote expo-*, sempre use npx expo install <package>.

Como sei se um pacote funciona no Expo Go?

Verifique o cabeçalho da documentação do pacote - "Incluído no Expo Go" significa que o módulo é distribuído no cliente Go para seu SDK.
Plugins de configuração e código nativo personalizado requerem um build de desenvolvimento de qualquer maneira.

Preciso reconstruir após adicionar um pacote Expo apenas JS?

Se o pacote não tiver código nativo e nenhum plugin de configuração, uma reinicialização do Metro é suficiente.
Se ele adicionar código nativo ou um plugin, execute npx expo prebuild ou um novo build EAS.

Onde encontro versões compatíveis?

npx expo install expo-camera
npx expo doctor

A referência do Expo SDK lista cada versão de módulo para o SDK 57.

Relacionado

expo-notifications - notificações push e locais
expo-location - localização em primeiro plano e em segundo plano
expo-file-system - armazenamento do dispositivo
expo-secure-store & expo-crypto - segredos e hashing
../expo-platform/expo-platform-basics/expo-platform-basics.md - fundamentos da plataforma
Boas Práticas de Pacotes do Expo SDK - resumo da seçã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).

Noções Básicas do Expo SDK

Buscar na documentação

Noções Básicas do Expo SDK