Noções Básicas de Integração

10 exemplos de configuração da máquina no primeiro dia - Xcode, Android Studio, EAS CLI, simuladores e fixação do SDK 57 - para que um novo membro da equipe execute o aplicativo antes do almoço.

Pré-requisitos

Clone o repositório da equipe e confirme o contrato do SDK em package.json antes de instalar as ferramentas nativas. Se o projeto usar o template padrão, espere Expo Router e fluxo gerenciado (sem ios/ / android/ commitados até o prebuild ou EAS).

git clone git@github.com:your-org/your-app.git
cd your-app
node -v   # espere 20.x
cat package.json | grep '"expo"'

Pilha de destino para esta seção:

{
  "engines": { "node": ">=20.0.0" },
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Ferramentas: Estes exemplos têm como alvo Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. Veja Noções Básicas de Configuração de Projeto para flags de scaffold e layout de pastas.

Exemplos Básicos

1. Node 20 e Gerenciador de Pacotes

Instale o Node 20 LTS com nvm, fnm ou mise - as ferramentas do SDK 57 e o EAS CLI o esperam.

# Exemplo nvm
nvm install 20
nvm use 20
node -v   # v20.x.x
 
npm install
# ou: corepack enable && pnpm install

{
  "engines": {
    "node": ">=20.0.0"
  }
}

• Um único lockfile no repositório - use o mesmo gerenciador de pacotes que a equipe documenta em CONTRIBUTING.md
• npm ci em CI; localmente npm install é suficiente após o clone
• Se engines falhar, corrija o Node antes de perseguir erros do Metro - Node incorreto causa falhas de transform crípticas

Relacionado: Noções Básicas de Configuração de Projeto - higiene de lockfile e .gitignore

2. Verificação do Pin do SDK 57

A versão do pacote expo é o contrato de compatibilidade para cada módulo expo-*.

npm install
npx expo-doctor
npx expo install --check

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

• npx expo-doctor compara seu grafo com a matriz do SDK 57 - execute-o no primeiro dia e após cada git pull
• npx expo install <pkg> resolve versões de peer - nunca escolha manualmente expo-camera sem ele
• Sintoma de incompatibilidade: tela vermelha mencionando versão do módulo nativo ou erros de parse do Hermes
• Novas contratações não devem atualizar o SDK na primeira semana, a menos que designado - fixe primeiro, atualize depois

Relacionado: Templates create-expo-app - scaffold default@sdk-57

3. Variáveis de Ambiente e Segredos

Copie o arquivo de exemplo .env antes da primeira execução - URLs de API ausentes causam telas em branco silenciosas.

cp .env.example .env.local

# .env.example (commitado)
EXPO_PUBLIC_API_URL=https://api.staging.example.com
# Segredos EAS - não em .env para builds de produção

// app.config.ts - exponha variáveis públicas via extra quando necessário
export default {
  expo: {
    extra: {
      apiUrl: process.env.EXPO_PUBLIC_API_URL,
    },
  },
};

• Variáveis EXPO_PUBLIC_* são incorporadas ao bundle JS - nunca coloque chaves privadas aqui
• Segredos de produção vivem em Variáveis de Ambiente EAS, não em arquivos .env do laptop
• Peça ao seu líder os links do 1Password / vault para EXPO_TOKEN, contas de staging e convites do TestFlight
• Reinicie o Metro após alterar variáveis de ambiente: npx expo start -c

4. Primeira Execução - Metro e Expo Go

Confirme se o JavaScript inicia antes de instalar IDEs nativas de vários gigabytes.

npx expo start
# pressione i para simulador iOS (requer Xcode)
# pressione a para emulador Android (requer Android Studio)
# escaneie o QR com o Expo Go em um dispositivo físico

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

• Expo Go é o mais rápido para trabalho com Router e UI - módulos nativos limitados
• expo start -c limpa o cache do Metro quando os imports parecem desatualizados após a troca de branches
• Se o projeto usar expo-dev-client, o primeiro dia pode exigir um build de desenvolvimento - verifique eas.json para o perfil development
• Critério de sucesso: a tela inicial carrega, sem redbox, tsc --noEmit passa

Relacionado: Noções Básicas do Expo Router - rotas baseadas em arquivos em app/

5. Xcode e Simulador iOS (macOS)

O desenvolvimento iOS requer o Xcode da Mac App Store e as ferramentas de linha de comando.

xcode-select --install
sudo xcodebuild -license accept
xcode-select -p
# /Applications/Xcode.app/Contents/Developer
 
# Lista de simuladores
xcrun simctl list devices available
 
# Abre o aplicativo Simulador
open -a Simulator

npx expo start --ios
# ou: npx expo run:ios

• Instale o Xcode 16+ compatível com o SDK 57 - combine com o que CI/EAS usa quando documentado
• A primeira execução de run:ios pode acionar o CocoaPods (pod install) se ios/ existir ou após o prebuild
• Apple Silicon: simuladores são arm64 - mais rápidos que imagens x86 do Rosetta
• Usuários de Windows/Linux usam EAS Build para artefatos iOS - nenhuma compilação local necessária

6. Android Studio e Emulador

Builds Android precisam do Android Studio com SDK Platform 35 e um dispositivo virtual (AVD).

# Após a instalação do Android Studio - defina ANDROID_HOME
export ANDROID_HOME=$HOME/Library/Android/sdk   # macOS
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
 
adb devices
emulator -list-avds

Android Studio → Gerenciador de SDK:

• Plataformas de SDK: Android 15 (API 35) - corresponde aos padrões do RN 0.86
• Ferramentas de SDK: Android SDK Build-Tools, Platform-Tools, Emulator

npx expo start --android

• Crie um AVD com a imagem Google Play ao testar recursos do Play Services
• adb reverse ajuda o Metro a alcançar APIs localhost: adb reverse tcp:8081 tcp:8081
• Habilite a depuração USB em dispositivos Android físicos para desenvolvimento no dispositivo

7. EAS CLI e Conta Expo

O EAS CLI conecta sua máquina ao serviço de build na nuvem da Expo - necessário para binários no formato de loja.

npm install -g eas-cli@latest
# ou localmente no projeto: npx eas-cli@latest
 
eas login
eas whoami
 
cd your-app
eas build:configure   # cria eas.json se ausente

// eas.json (iniciador mínimo)
{
  "cli": { "version": ">= 16.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  }
}

• eas login usa sua conta Expo - solicite um convite de organização ao líder mobile
• eas build:configure vincula o ID do projeto em app.config.ts via extra.eas.projectId
• CI usa a conta robô EXPO_TOKEN - humanos usam eas login; nunca comite tokens
• Primeiro build na nuvem: eas build --profile development --platform ios --local opcional; o padrão é na nuvem

Relacionado: Noções Básicas do EAS Build - perfis, credenciais, primeiro build

Exemplos Intermediários

8. Cliente de Desenvolvimento vs Expo Go

Quando o aplicativo adiciona módulos nativos personalizados ou plugins de configuração, o Expo Go não é suficiente - instale um cliente de desenvolvimento.

npx expo install expo-dev-client
eas build --profile development --platform ios
# Instale o IPA via QR do painel EAS
npx expo start --dev-client

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": { "simulator": true }
    }
  }
}

• O perfil de desenvolvimento inclui expo-dev-client e código nativo de plugins de configuração
• Builds de simulador (ios.simulator: true) instalam mais rapidamente para trabalho de UI apenas iOS
• Reconstrua o cliente de desenvolvimento quando as dependências nativas mudarem - apenas mudanças JS ainda recarregam a quente
• Documente qual perfil os novos contratados devem instalar no documento de integração

Relacionado: Noções Básicas do EAS Build - developmentClient: true

9. Atalhos de Simulador e Emulador

Padronize nomes de dispositivos para que sessões de pareamento e capturas de tela correspondam.

# iOS - inicia o simulador nomeado
xcrun simctl boot "iPhone 16"
open -a Simulator
 
# Android - inicia AVD pelo nome
emulator -avd Pixel_8_API_35 &
 
# Expo visa um dispositivo específico
npx expo run:ios --device "iPhone 16"
npx expo run:android --device Pixel_8_API_35

// package.json - atalhos da equipe (opcional)
{
  "scripts": {
    "ios:16": "expo run:ios --device 'iPhone 16'",
    "android:pixel": "expo run:android --device Pixel_8_API_35"
  }
}

• Mesma classe de dispositivo em revisões de design - evite surpresas do tipo "funciona no meu iPhone SE"
• Reinicie simuladores quando o Keychain ou o estado de push ficarem corrompidos: xcrun simctl erase all (destrutivo)
• Dispositivos físicos: registre UDIDs para distribuição interna iOS nas credenciais EAS

10. Checklist de Verificação do Primeiro Dia

Execute este bloco de script antes de abrir seu primeiro PR - ele captura 90% dos desvios de integração.

node -v                    # 20.x
npm ci
npx expo-doctor
npm run typecheck          # ou: npx tsc --noEmit
npm run lint
npm test -- --passWithNoTests
npx expo start

## Trecho de CONTRIBUTING.md - Configuração da máquina
1. Node 20 via nvm
2. Clone + `npm ci`
3. `cp .env.example .env.local` (peça valores no canal #mobile)
4. `npx expo-doctor` - deve passar
5. `npx expo start` - smoke test iOS sim + Android emu
6. `eas login` + convite da organização
7. Instale o cliente de desenvolvimento do perfil `development` do EAS se o repositório tiver expo-dev-client

• Adicione npx expo customize tsconfig.json se as rotas tipadas falharem em um clone limpo
• Tire um print do expo-doctor passando no seu PR de integração se sua equipe rastreia checklists de contratação
• Escalone para o canal da plataforma quando o doctor falhar em um clone novo - provavelmente desvio do repositório, não erro do contratado

Relacionado: Melhores Práticas de Configuração de Projeto - convenções que sobrevivem à segunda semana

FAQs

Relacionados

• Noções Básicas de Configuração de Projeto - scaffold, pin do SDK, layout de pastas
• Noções Básicas do EAS Build - primeiro build na nuvem
• Noções Básicas do Expo Router - modelo mental de app/
• Caminho de Aprendizagem da Primeira Semana - o que aprender após a configuração da máquina
• Checklist do Tour pelo Codebase - onde o código vive

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