Noções Básicas da Plataforma Expo

10 exemplos para você começar com a Plataforma Expo - 7 básicos e 3 intermediários.

Pré-requisitos

Projetos Expo são criados com create-expo-app, que fixa o SDK, a configuração do Metro e o layout padrão do TypeScript em uma etapa.

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

Confirme o pin do SDK em package.json antes de instalar qualquer outra coisa:

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

Inicie o servidor de desenvolvimento e abra o aplicativo em um dispositivo ou simulador:

npx expo start

Pressione i para o Simulador iOS, a para Android, ou escaneie o código QR com o Expo Go. Cada exemplo executável abaixo pode substituir App.tsx no projeto que você acabou de criar.

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. Expo como Camada de Plataforma

O Expo envolve o React Native com ferramentas, um conjunto de módulos selecionado e um projeto nativo gerenciado - seu código de UI permanece RN padrão.

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}>Expo + React Native</Text>
      <Text style={styles.body}>
        Mesmos primitivos View/Text - Expo fornece o servidor de desenvolvimento,
        configuração e bootstrap nativo.
      </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 },
});

• Você ainda escreve componentes React Native - Expo não é um framework de UI separado
• Pacotes como expo-status-bar são enviados como módulos Expo com código nativo pré-compilado para o SDK
• O fluxo de trabalho gerenciado significa que o Expo é o proprietário da geração de ios/ e android/ via prebuild, a menos que você faça eject ou execute em modo bare
• Adote o Expo quando quiser iteração mais rápida, atualizações consistentes e EAS Build/Update sem manter projetos nativos desde o primeiro dia

Relacionado: Guia de Início Rápido create-expo-app - modelos e verificação de primeira execução | Expo Modules Core - como os módulos nativos fazem o bootstrap

2. Layout Padrão do Projeto

Um novo aplicativo Expo é uma árvore pequena e previsível - aprenda esses arquivos antes de adicionar recursos.

MyExpoApp/
├── App.tsx              # Componente raiz (UI de entrada)
├── app.json             # Manifest estático (ou app.config.ts)
├── package.json         # Dependências e scripts fixados pelo SDK
├── tsconfig.json
├── assets/              # Ícones, splash, imagens empacotados no momento da build
└── node_modules/

• App.tsx é a raiz padrão - projetos Expo Router substituem isso por um diretório app/ em vez disso
• app.json (ou app.config.ts) é a única fonte de verdade para identidade do aplicativo, ícones e permissões nativas
• Arquivos assets/ são referenciados por URI na configuração (icon, splash) e importados em componentes
• Nenhuma pasta ios/ ou android/ ainda no modo puramente gerenciado - elas aparecem após npx expo prebuild ou uma build EAS

Relacionado: Guia de Início Rápido create-expo-app - escolhas de modelo e referência de script

3. Pin do SDK em package.json

A versão do pacote expo é o contrato que todos os outros módulos Expo devem satisfazer.

{
  "name": "my-expo-app",
  "main": "expo/AppEntry.js",
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios"
  },
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

• expo ~57.0.4 fixa o projeto ao SDK 57 - misturar módulos do SDK 56 com expo do SDK 57 causa falhas de compilação nativa
• main: "expo/AppEntry.js" conecta o Metro ao bootstrap do Expo, que registra seu componente raiz
• Scripts padrão delegam para expo start para que as flags LAN, tunnel e dev-client permaneçam consistentes entre a equipe
• Após clonar, execute npm install e depois npx expo doctor para capturar desvios de versão antes da sua primeira build

Relacionado: Atualizando Versões do Expo SDK - bumps intencionais e expo install --fix

4. Campos de Identidade em app.json

Essas chaves de manifesto definem como o binário aparece nas telas iniciais dos dispositivos e nas lojas de aplicativos.

{
  "expo": {
    "name": "My Expo App",
    "slug": "my-expo-app",
    "version": "1.0.0",
    "scheme": "myexpoapp",
    "orientation": "portrait",
    "icon": "./assets/icon.png",
    "splash": {
      "image": "./assets/splash-icon.png",
      "resizeMode": "contain",
      "backgroundColor": "#ffffff"
    },
    "ios": {
      "bundleIdentifier": "com.example.myexpoapp"
    },
    "android": {
      "package": "com.example.myexpoapp"
    }
  }
}

• name é o rótulo visível para o usuário; slug é o identificador do projeto Expo seguro para URL
• scheme registra um esquema de URL personalizado para deep links (myexpoapp://)
• bundleIdentifier / package devem ser únicos por aplicativo - alterá-los após o lançamento na loja cria uma nova listagem
• Ícones e caminhos de splash são resolvidos no tempo de build, não buscados pela rede

Relacionado: app.json & app.config.js - configuração dinâmica e manifestos multi-ambiente

5. Inicie o Servidor de Desenvolvimento

expo start inicia o Metro, imprime um QR code e faz hot-reloads em App.tsx ao salvar.

# Padrão: URL LAN para dispositivos na mesma rede
npx expo start
 
# Limpa o cache do Metro após alterações de dependência ou babel
npx expo start --clear
 
# Tunnel quando LAN/firewall bloqueia dispositivo ↔ laptop (mais lento, mas confiável)
npx expo start --tunnel

import { useState } from "react";
import { Pressable, StyleSheet, Text, View } from "react-native";
 
export default function App() {
  const [count, setCount] = useState(0);
 
  return (
    <View style={styles.container}>
      <Text style={styles.count}>{count}</Text>
      <Pressable style={styles.button} onPress={() => setCount((c) => c + 1)}>
        <Text style={styles.buttonText}>Incrementar - salve para hot reload</Text>
      </Pressable>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", alignItems: "center", gap: 16 },
  count: { fontSize: 48, fontWeight: "700" },
  button: { backgroundColor: "#2563eb", paddingHorizontal: 20, paddingVertical: 12, borderRadius: 10 },
  buttonText: { color: "#fff", fontWeight: "600" },
});

• O Metro agrupa JavaScript sob demanda - Fast Refresh preserva o estado do componente quando possível
• Use --clear quando os imports não resolverem corretamente após adicionar pacotes ou alterar babel.config.js
• LAN é o mais rápido; tunnel troca latência por alcançabilidade em Wi-Fi corporativo ou dispositivos remotos
• O terminal também aceita i / a para iniciar simuladores sem redigitar flags

Relacionado: Expo Go vs Builds de Desenvolvimento - qual cliente abre a partir deste comando

6. Instalações Seguras de Versão com expo install

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

# Adiciona um módulo testado contra o SDK 57
npx expo install expo-camera expo-file-system
 
# Após uma edição manual de package.json ou um bump de SDK - reconcilie todas as dependências Expo
npx expo install --fix

• npx expo install lê sua versão expo fixada e escolhe lançamentos de módulos nativos compatíveis
• Simplesmente npm install expo-camera@latest pode puxar um módulo construído para um SDK mais novo e quebrar a compilação iOS/Android
• --fix é o primeiro comando a ser executado após atualizar expo em package.json
• Plugins de configuração para alguns módulos (câmera, notificações) também exigem entradas em app.json - instalar é apenas o primeiro passo

Relacionado: Atualizando Versões do Expo SDK - doctor, changelog e alinhamento com RN

7. Pré-visualize com Expo Go

Expo Go é um aplicativo sandbox com módulos nativos pré-compilados - ideal para aprender e trabalhar em UI sem compilar código nativo.

import { CameraView, useCameraPermissions } from "expo-camera";
import { Pressable, StyleSheet, Text, View } from "react-native";
 
export default function App() {
  const [permission, requestPermission] = useCameraPermissions();
 
  if (!permission?.granted) {
    return (
      <View style={styles.center}>
        <Text style={styles.message}>O acesso à câmera é necessário.</Text>
        <Pressable style={styles.button} onPress={requestPermission}>
          <Text style={styles.buttonText}>Conceder permissão</Text>
        </Pressable>
      </View>
    );
  }
 
  return <CameraView style={styles.camera} facing="back" />;
}
 
const styles = StyleSheet.create({
  center: { flex: 1, justifyContent: "center", alignItems: "center", gap: 12, padding: 24 },
  message: { fontSize: 16, textAlign: "center" },
  button: { backgroundColor: "#2563eb", paddingHorizontal: 20, paddingVertical: 10, borderRadius: 8 },
  buttonText: { color: "#fff", fontWeight: "600" },
  camera: { flex: 1 },
});

• Escaneie o QR de npx expo start com o Expo Go - nenhum Xcode ou Android Studio é necessário para este ciclo
• O Expo Go inclui apenas módulos enviados em sua build da loja; código nativo personalizado ou módulos não lançados não rodarão
• APIs de permissão (useCameraPermissions) ainda executam prompts reais do sistema operacional dentro do shell do Expo Go
• Quando você ultrapassar o conjunto de módulos do Expo Go, mude para uma build de desenvolvimento - o mesmo bundle JS, seu próprio binário nativo

Relacionado: Expo Go vs Builds de Desenvolvimento - checklist de decisão e expo-dev-client

Exemplos Intermediários

8. app.config.ts Consciente do Ambiente

Substitua o app.json estático por configuração TypeScript quando os IDs de bundle, nomes ou hosts de API diferirem por ambiente.

import { ExpoConfig, ConfigContext } from "expo/config";
 
const APP_VARIANT = process.env.APP_VARIANT ?? "development";
 
export default ({ config }: ConfigContext): ExpoConfig => {
  const isProd = APP_VARIANT === "production";
 
  return {
    ...config,
    name: isProd ? "My Expo App" : "My Expo App (Dev)",
    slug: "my-expo-app",
    ios: {
      ...config.ios,
      bundleIdentifier: isProd
        ? "com.example.myexpoapp"
        : "com.example.myexpoapp.dev",
    },
    android: {
      ...config.android,
      package: isProd ? "com.example.myexpoapp" : "com.example.myexpoapp.dev",
    },
    extra: {
      apiUrl: isProd ? "https://api.example.com" : "https://staging.example.com",
      appVariant: APP_VARIANT,
    },
  };
};

APP_VARIANT=development npx expo start
APP_VARIANT=production npx eas build --profile production

• app.config.ts é avaliado no momento da build e prebuild - não a cada recarregamento do Metro
• Use ...config para que o Expo CLI mescle os padrões (plugins, atualizações) em vez de ignorá-los silenciosamente
• Coloque variáveis de ambiente não secretas em extra - leia-as com expo-constants no código do aplicativo
• Nunca incorpore chaves de API privadas aqui; use variáveis de ambiente EAS ou segredos de CI para valores sensíveis

Relacionado: app.json & app.config.js - plugins de configuração e padrões seguros para segredos | Ambientes & Variáveis de Ambiente EAS - separação dev/staging/prod

9. Quando Expo Go Não é Suficiente

Bibliotecas com código nativo personalizado, módulos nativos privados ou plugins de configuração que não estão no Expo Go exigem uma build de desenvolvimento.

npx expo install expo-dev-client
npx expo run:ios
# ou produza um cliente de desenvolvimento instalável via EAS:
npx eas build --profile development --platform ios

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": { "deploymentTarget": "15.1" },
          "android": { "minSdkVersion": 24 }
        }
      ]
    ]
  }
}

• expo-dev-client substitui o Expo Go como o shell nativo, mantendo o Metro com fast refresh
• npx expo run:ios / run:android gera projetos nativos localmente via prebuild, e então compila um cliente de desenvolvimento
• Plugins de configuração modificam projetos nativos no prebuild - eles são ignorados pelo Expo Go mesmo que as importações JavaScript sejam bem-sucedidas
• Permaneça no fluxo de trabalho gerenciado: comite app.config.ts e deixe o EAS Build executar o prebuild em CI em vez de editar manualmente ios/ quando possível

Relacionado: Expo Go vs Builds de Desenvolvimento - matriz de recursos | Migração de Gerenciado para Bare - mantendo caminhos de atualização quando pastas nativas existem

10. Vincule uma Conta Expo e um Projeto EAS

Associar o aplicativo a um projeto Expo desbloqueia builds na nuvem, submissão, atualizações e segredos com escopo de organização.

npx expo login
npx eas init

{
  "expo": {
    "name": "My Expo App",
    "slug": "my-expo-app",
    "owner": "my-org",
    "extra": {
      "eas": {
        "projectId": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

import Constants from "expo-constants";
import { Text, View } from "react-native";
 
export default function App() {
  const projectId = Constants.expoConfig?.extra?.eas?.projectId;
 
  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Text>Projeto EAS: {projectId ?? "não vinculado"}</Text>
    </View>
  );
}

• eas init cria ou vincula um projeto sob sua conta Expo e escreve extra.eas.projectId
• owner definido como um slug de organização direciona builds e credenciais para a equipe, não para uma conta pessoal
• O projectId é estável entre as alterações do ID do bundle - os serviços EAS o utilizam como chave, não apenas o slug
• Vincule cedo em projetos greenfield para que os perfis de build de pré-visualização, staging e produção compartilhem uma única loja de credenciais

Relacionado: Conta Expo, Projetos e Permissões - funções e governança multi-aplicativo | Ambientes & Variáveis de Ambiente EAS - segredos por ambiente

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