Noções Básicas de Desenvolvimento Local

10 exemplos para você começar com o Desenvolvimento Local - 7 básicos e 3 intermediários.

Pré-requisitos

O desenvolvimento local com Expo é um servidor de desenvolvimento Metro no seu laptop mais um aplicativo cliente em um simulador, emulador ou dispositivo físico. Crie o scaffold uma vez e, em seguida, reutilize o mesmo comando de inicialização todos os dias.

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

Confirme o "pin" do SDK antes da sua primeira execução:

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

Instale o Expo Go em um dispositivo físico (App Store / Play Store) se você planeja escanear códigos QR. Simuladores e emuladores não precisam do Expo Go - a CLI os abre diretamente.

Ferramentas: Estes exemplos visam o Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. O Metro serve JavaScript na porta 8081 por padrão.

Exemplos Básicos

1. Iniciar o Servidor de Desenvolvimento

npx expo start é o ponto de entrada diário - ele inicia o Metro, exibe URLs de conexão e mostra um código QR no terminal.

cd MyDevApp
npx expo start

› Metro aguardando em exp://192.168.1.42:8081
› Escaneie o código QR acima com o Expo Go (Android) ou o aplicativo Câmera (iOS)
 
› Pressione i │ abrir simulador iOS
› Pressione a │ abrir emulador Android
› Pressione r │ recarregar aplicativo
› Pressione ? │ mostrar todos os comandos

• O Metro faz o bundle sob demanda - salvar um arquivo aciona o Fast Refresh sem uma reconstrução nativa completa
• A URL exp:// impressa é o que simuladores, Expo Go e clientes de desenvolvimento usam para baixar o bundle JS
• Deixe este terminal em execução; abra uma segunda aba para git, testes ou comandos eas
• Se o servidor sair imediatamente, execute npx expo doctor para capturar incompatibilidades de versão do SDK ou Node antes de depurar problemas de rede

Relacionado: Noções Básicas da Plataforma Expo - layout do projeto e "pin" do SDK | Hot Reload vs Fast Refresh - o que sobrevive a um salvamento

2. Modo LAN (Padrão)

LAN anuncia o IP local do seu laptop para que telefones e tablets na mesma rede Wi‑Fi possam alcançar o Metro - sem sinalizadores extras necessários.

# LAN é o padrão - Metro anuncia o IP local da sua máquina
npx expo start

# Verificação de sanidade para que o dispositivo possa alcançar sua máquina (substitua pelo IP que o Metro imprimiu)
curl -I http://192.168.1.42:8081/status

• LAN mantém o tráfego em sua rede local - menor latência e o padrão correto para Wi‑Fi de escritório e doméstico
• Ambos os dispositivos devem estar na mesma sub-rede; redes de convidados e isolamento de clientes geralmente bloqueiam o tráfego do telefone ↔ laptop
• VPNs em qualquer um dos lados frequentemente quebram a LAN - desconecte a VPN no dispositivo ou laptop antes de mudar para tunnel
• Firewalls corporativos que bloqueiam a porta 8081 de entrada são o motivo mais comum para a LAN "funcionar no simulador, mas não no telefone"

Relacionado: Teste em Dispositivo Físico - depuração USB e pareamento sem fio quando a LAN é não confiável

3. Modo Tunnel

Tunnel roteia o Metro através do relay da Expo para que um dispositivo possa carregar seu bundle mesmo quando a LAN estiver bloqueada - ao custo de velocidade.

# Use quando os escaneamentos de QR da LAN falharem em Wi-Fi de convidados, VPN ou pareamento remoto
npx expo start --tunnel

› Metro aguardando em exp://u3k1-xxxxx.exp.direct:80
› Tunnel pronto.

• Tunnel é mais lento que LAN - espere carregamentos iniciais mais longos e Fast Refresh ocasionalmente lento
• A primeira execução do tunnel pode solicitar que você faça login com npx expo login para que a Expo possa provisionar o URL do relay
• Prefira LAN sempre que funcionar; reserve o tunnel para demonstrações, dispositivos de clientes fora da rede ou Wi‑Fi corporativo restrito
• Se o tunnel travar em "Conectando…", verifique se o HTTPS de saída está permitido e tente novamente com npx expo start --tunnel --clear

Relacionado: Teste em Dispositivo Físico - quando builds internos ou USB substituem o tunnel completamente

4. Fluxo de Trabalho com Código QR e Expo Go

Escanear o código QR do terminal é a maneira mais rápida de abrir um projeto em um dispositivo real sem Xcode ou Android Studio.

npx expo start
# Aponte seu telefone para o bloco de código QR ASCII no terminal

• O QR codifica o mesmo URL exp:// que o Metro imprime - escanear é apenas um atalho para digitar o URL manualmente
• Expo Go envia um runtime nativo corrigido; ele só carrega projetos cujos módulos nativos estão incluídos nesse build do Expo Go para o SDK 57
• Após a primeira abertura, o projeto aparece em Recentemente abertos dentro do Expo Go para relançamento com um toque
• Se o escaneamento for bem-sucedido, mas o aplicativo travar em "Baixando…", volte para o tunnel (Exemplo 3) ou confirme a alcançabilidade da LAN (Exemplo 2)

Relacionado: expo-dev-client - quando o Expo Go não é mais suficiente | Simulador iOS e Emulador Android - fluxos de trabalho com simulador primeiro

5. Atalhos de Simulador e Emulador

Com o Metro em execução, atalhos de terminal de uma única tecla iniciam simuladores sem memorizar comandos específicos da plataforma.

npx expo start

• Atalhos funcionam apenas no terminal onde expo start está em foco - eles não são atalhos globais
• i / a não compilam nada por si só; eles iniciam o simulador e fazem deep-link no seu servidor Metro em execução
• Se a relatar nenhum emulador, crie um AVD no Android Studio → Gerenciador de Dispositivos, então pressione a novamente
• j abre a história do depurador do RN 0.86 - inspetor de elementos, desempenho e árvore de componentes sem Flipper

Relacionado: Simulador iOS e Emulador Android - configuração de AVD, snapshots e matriz de dispositivos | React Native DevTools - painéis de inspetor e desempenho

6. Limpar Cache do Metro

Bundles desatualizados após alterações de dependência ou configuração são corrigidos reiniciando o Metro com um cache limpo.

# Após npm install, atualização de SDK ou edições em babel.config.js
npx expo start --clear
 
# Combinar com um modo host quando necessário
npx expo start --clear --tunnel

# Opção nuclear quando --clear não é suficiente (macOS / Linux)
rm -rf node_modules/.cache .expo
npx expo start --clear

• --clear limpa o cache de transformação do Metro - a primeira recarga depois é mais lenta, então a velocidade retorna ao normal
• Execute com --clear após npx expo install --fix, adicionar um plugin Babel Reanimated ou atualizar expo em package.json
• Sintomas que gritam "limpe o cache": imports resolvem para caminhos antigos, Fast Refresh nunca pega edições, telas vermelhas referenciando arquivos excluídos
• Excluir .expo redefine o estado local da CLI (credenciais de tunnel em cache, último dispositivo aberto) - seguro, mas você pode precisar escanear o QR novamente

Relacionado: Hot Reload vs Fast Refresh - diagnosticando bundles desatualizados vs perda de estado | Melhores Práticas da Expo CLI - lista de verificação de higiene diária

7. Scripts de Equipe em package.json

Codifique o modo host e os pontos de entrada da plataforma em package.json para que cada desenvolvedor execute comandos idênticos.

{
  "scripts": {
    "start": "expo start",
    "start:clear": "expo start --clear",
    "start:tunnel": "expo start --tunnel",
    "ios": "expo start --ios",
    "android": "expo start --android",
    "ios:device": "expo run:ios --device"
  }
}

npm run start          # LAN + QR - padrão diário
npm run start:tunnel   # Sessão de pareamento para QA em outra rede
npm run ios            # Atalho do simulador sem um terminal interativo

• expo start --ios e --android combinam a inicialização do Metro e o lançamento do cliente - útil em scripts de smoke test de CI e tarefas do VS Code
• expo run:ios --device compila e instala em um iPhone conectado (requer configuração de assinatura de desenvolvimento Apple)
• Fixe scripts em package.json em vez de documentar sinalizadores pontuais no README - o onboarding permanece copiável e colável
• Combine start:clear com um hook pós-instalação ou documente "execute após cada git pull que toque em package-lock.json"

Relacionado: Melhores Práticas da Expo CLI - convenções de nomenclatura e runbooks de solução de problemas compartilhados

Exemplos Intermediários

8. Cliente de Desenvolvimento (expo-dev-client)

Depois de adicionar módulos nativos fora do runtime do Expo Go, inicie o Metro no modo dev-client para que os códigos QR e URLs abram seu build personalizado em vez do Expo Go.

# Instale a biblioteca dev-client (uma vez por projeto)
npx expo install expo-dev-client
 
# Construa e instale o shell nativo localmente (primeira vez, ou após alterações nativas)
npx expo run:ios
# npx expo run:android
 
# Iteração diária de JS - mesmo servidor Metro, cliente diferente
npx expo start --dev-client

{
  "scripts": {
    "start": "expo start --dev-client",
    "ios": "expo start --dev-client --ios",
    "android": "expo start --dev-client --android"
  }
}

• --dev-client altera o payload do QR e o deep link para que os builds de desenvolvimento instalados se conectem automaticamente
• Você ainda obtém Fast Refresh - apenas o shell nativo é pré-construído; JavaScript é carregado do Metro como de costume
• Reconstrua o cliente de desenvolvimento após alterações nativas (plugins em app.json, novos módulos nativos, atualizações de SDK) - edições apenas de JS não exigem reconstrução
• Pressione s no terminal interativo para alternar entre Expo Go e build de desenvolvimento quando ambos os clientes estiverem instalados

Relacionado: expo-dev-client - configurações do launcher e iteração de módulos nativos | Expo Go vs Builds de Desenvolvimento - escolhendo um modelo de cliente

9. Seleção de Host Localhost vs LAN

Simuladores na mesma máquina podem usar localhost; dispositivos físicos sempre precisam de um endereço LAN ou tunnel alcançável.

# Apenas simuladores - Metro escuta em 127.0.0.1
npx expo start --localhost
 
# Telefone físico na mesa - LAN é o padrão (sem sinalizador extra)
npx expo start
 
# Forçar um IP específico quando o Metro escolher a interface errada (VPN, Docker, ponte Thunderbolt)
REACT_NATIVE_PACKAGER_HOSTNAME=192.168.1.42 npx expo start

• --localhost evita anunciar IPs em redes não confiáveis - útil em Wi‑Fi de cafeteria quando você só precisa do simulador
• REACT_NATIVE_PACKAGER_HOSTNAME substitui a detecção automática quando seu Mac tem várias interfaces ativas e o Metro imprime a incorreta
• Emuladores Android às vezes precisam de adb reverse ao usar configurações com forte dependência de localhost - prefira --host lan para sessões mistas de simulador + hardware
• Documente o sinalizador de host que sua equipe usa no README - grupos "sempre tunnel" e "sempre LAN" se desviam rapidamente sem padrões de script

Relacionado: Teste em Dispositivo Físico - depuração sem fio quando as substituições de nome do host não são suficientes

10. Fluxo de Trabalho Diário de Ponta a Ponta

Combine o tipo de cliente, modo host, política de cache e entrada do depurador em um loop repetível para projetos do SDK 57.

#!/usr/bin/env bash
# scripts/dev.sh - helper opcional da equipe
set -euo pipefail
 
CLIENT="${1:-dev}"   # dev | go
HOST="${2:-lan}"     # lan | tunnel | localhost
 
FLAGS=()
case "${HOST}" in
  tunnel)     FLAGS+=(--tunnel) ;;
  localhost)  FLAGS+=(--localhost) ;;
  lan)        ;; # padrão - sem sinalizador extra
  *) echo "Host desconhecido: ${HOST}" >&2; exit 1 ;;
esac
 
if [[ "${CLIENT}" == "dev" ]]; then
  FLAGS+=(--dev-client)
elif [[ "${CLIENT}" == "go" ]]; then
  FLAGS+=(--go)
fi
 
# Limpa o cache às segundas-feiras ou após alterações de dependência
if [[ "${CLEAR_CACHE:-}" == "1" ]]; then
  FLAGS+=(--clear)
fi
 
npx expo start "${FLAGS[@]}"

# Expo Go na LAN do escritório
./scripts/dev.sh go lan
 
# Cliente de desenvolvimento personalizado via tunnel para um dispositivo de QA remoto
./scripts/dev.sh dev tunnel
 
# Reinício de segunda-feira apenas para simulador com cache limpo
CLEAR_CACHE=1 ./scripts/dev.sh dev localhost

Ordem de solução de problemas quando o aplicativo não conecta:

1. Confirme se o Metro está em execução e se a porta 8081 não está sendo usada por outro projeto RN.
2. Tente novamente npx expo start --clear após qualquer npm install.
3. Mude o host: LAN → tunnel (ou defina REACT_NATIVE_PACKAGER_HOSTNAME).
4. Verifique o tipo de cliente: Expo Go apenas para módulos SDK, --dev-client após expo run:*.
5. Pressione j para anexar React Native DevTools se o aplicativo carregar, mas se comportar incorretamente.

• Scriptar a matriz de sinalizadores evita a deriva de "funciona na minha máquina" entre colegas que usam Expo Go e dev-client
• CLEAR_CACHE=1 como uma variável de ambiente opcional é melhor do que sempre passar --clear, que penaliza cada inicialização desnecessariamente
• Mantenha os caminhos go e dev explícitos - a detecção automática do cliente instalado falha silenciosamente quando ambos os aplicativos estão no dispositivo
• Quando a etapa 5 ainda falhar, capture os logs do Metro e reproduza no simulador (i) para separar problemas de rede de defeitos de JavaScript

Relacionado: React Native DevTools - anexe o depurador após o bundle carregar | Flipper e Depuradores Alternativos - inspeção em nível nativo quando as ferramentas JS não são suficientes | Melhores Práticas da Expo CLI - convenções de equipe e entrega de CI

Versões da pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).