React Native Essencial: preparação do ambiente e primeiros testes

Objetivo do ambiente

Um ambiente funcional de React Native precisa garantir três coisas: (1) JavaScript/TypeScript rodando com um runtime (Node.js), (2) dependências instaladas e resolvidas com um gerenciador de pacotes (npm/yarn/pnpm), e (3) toolchains nativas para compilar e executar no Android (Android SDK/Emulador) e no iOS (Xcode/Simulador). A validação do setup é feita criando e executando um app mínimo em Android e iOS, observando o output do Metro e os logs do console.

Node.js e gerenciadores de pacotes

Instalar Node.js (LTS)

Use uma versão LTS do Node.js para reduzir incompatibilidades com bibliotecas nativas. Após instalar, valide no terminal:

node -v
npm -v

Escolher um gerenciador: npm vs yarn vs pnpm

• npm: vem com o Node, suficiente para a maioria dos projetos.
• yarn: popular em monorepos e times que padronizam scripts; bom desempenho.
• pnpm: instala dependências com store global e links, economiza espaço e costuma ser rápido; exige atenção extra em alguns scripts nativos antigos.

Valide versões (se você usar um deles):

yarn -v
pnpm -v

Recomendação prática: escolha um gerenciador por projeto e mantenha consistente (inclusive no CI). Se o projeto usa package-lock.json, prefira npm; se usa yarn.lock, prefira yarn; se usa pnpm-lock.yaml, prefira pnpm.

React Native CLI vs Expo (quando usar cada um)

Conceito

Existem dois fluxos comuns para criar apps React Native:

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

• React Native CLI (bare): você compila com Android Studio/Gradle e Xcode. Ideal quando precisa de controle total do código nativo, bibliotecas que exigem configuração nativa avançada, múltiplos flavors/schemes, integrações específicas de build.
• Expo (managed): você desenvolve com ferramentas do Expo e pode rodar rapidamente em emuladores/dispositivos. Ideal para começar rápido, reduzir configuração nativa e usar um conjunto amplo de APIs prontas. Se precisar de código nativo, pode usar config plugins e/ou migrar para um fluxo mais nativo quando necessário.

Regra prática: se você já sabe que precisará mexer em Gradle/Xcode frequentemente, comece com CLI. Se quer validar ideia/prototipar e manter o foco em UI e lógica, comece com Expo.

Instalação das CLIs

Para o React Native CLI, você normalmente usa o comando via npx (sem instalar globalmente):

npx react-native --version

Para o Expo, instale a CLI (ou use via npx). Uma forma comum:

npx expo --version

Android: Android Studio, SDK e AVD

Instalar e validar Android Studio

Instale o Android Studio e, dentro dele, garanta:

• Android SDK instalado (SDK Platforms).
• Android SDK Build-Tools e Platform-Tools (SDK Tools).
• Emulator e um AVD criado (Device Manager).

Variáveis de ambiente (SDK)

O React Native/Gradle precisa localizar o SDK. Em muitos casos o Android Studio configura automaticamente, mas quando não, defina:

• ANDROID_HOME (ou ANDROID_SDK_ROOT) apontando para a pasta do SDK.
• Adicionar ao PATH as pastas platform-tools e emulator.

Exemplo (macOS/Linux, ajuste o caminho):

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator

Valide se o adb está acessível:

adb version
adb devices

Criar e iniciar um emulador (AVD)

No Android Studio: Device Manager → crie um dispositivo (ex.: Pixel) → escolha uma imagem (preferencialmente x86_64) → finalize. Inicie o emulador e confirme que aparece em adb devices.

JDK (Java) e Gradle

Conceito

O build Android usa Gradle, que depende do Java (JDK). Versões incompatíveis de JDK são uma das causas mais comuns de erro.

Como validar o Java

java -version
javac -version

Se o Android Studio estiver configurado para usar um JDK embutido, ainda assim é útil ter um JDK compatível no sistema para ferramentas e scripts. Se houver erro de Java, verifique:

• JAVA_HOME apontando para o JDK correto.
• Se o terminal está usando o mesmo Java que o Android Studio.

Para inspecionar o caminho do Java em macOS:

/usr/libexec/java_home -V

iOS: Xcode, simulador e certificados básicos

Instalar Xcode e Command Line Tools

No macOS, instale o Xcode e aceite os termos. Depois, instale/valide as Command Line Tools:

xcodebuild -version
xcode-select -p

Se necessário, selecione o Xcode correto:

sudo xcode-select --switch /Applications/Xcode.app

Simulador

Abra o Xcode → Settings/Preferences → Platforms (ou Components) e garanta que há simuladores instalados. Você também pode listar simuladores via terminal:

xcrun simctl list devices

Certificados básicos (para rodar em dispositivo)

Para rodar em um iPhone físico, você precisa:

• Entrar com um Apple ID no Xcode (Accounts).
• Habilitar Automatically manage signing no target do app.
• Selecionar um Team e um Bundle Identifier único.

Para validar que o sistema de assinatura está acessível, tente abrir um projeto iOS e compilar para um dispositivo conectado (quando aplicável). Em simulador, assinatura costuma ser menos problemática.

Checklist de verificação (comandos rápidos)

Erros comuns e como resolver

1) ANDROID_HOME/SDK não encontrado

Sintomas: Gradle falha com mensagens sobre SDK, sdk.dir ausente, ou ferramentas não encontradas.

Correções:

• Confirme o caminho do SDK no Android Studio: Settings → Android SDK.
• Defina ANDROID_HOME (ou ANDROID_SDK_ROOT) e adicione platform-tools ao PATH.
• Alternativa por projeto: crie/edite android/local.properties com:

sdk.dir=/caminho/para/Android/sdk

2) Emulador não aparece em adb devices

Sintomas: adb devices vazio, ou emulador offline.

Correções:

• Reinicie o ADB:

adb kill-server
adb start-server
adb devices

• Abra o emulador pelo Device Manager e aguarde boot completo.
• Verifique se você adicionou platform-tools no PATH.

3) Erros de JDK/Gradle (Unsupported class file major version, etc.)

Sintomas: build Android falha com mensagens de versão do Java/bytecode.

Correções:

• Verifique java -version no terminal usado para build.
• Ajuste JAVA_HOME para um JDK compatível.
• Se o Android Studio usa um JDK diferente, alinhe o JDK do IDE e do terminal.

4) iOS: xcode-select apontando para local errado

Sintomas: comandos como xcodebuild falham, ou o build não encontra SDKs.

Correções:

sudo xcode-select --switch /Applications/Xcode.app
xcode-select -p
xcodebuild -version

5) Porta do Metro ocupada (8081) ou bundler duplicado

Sintomas: erro de porta em uso, app abre mas não carrega bundle.

Correções:

• Encerre processos antigos do Metro.
• Suba o Metro em outra porta (se necessário) e aponte o app para ela.

npx react-native start --port 8082

Primeiro teste com React Native CLI (bare)

1) Criar um app mínimo

No diretório onde você cria projetos:

npx react-native init MeuAppSetup

Entre na pasta:

cd MeuAppSetup

2) Subir o Metro

npx react-native start

Mantenha esse terminal aberto. O Metro é o bundler que serve o JavaScript para o app durante o desenvolvimento.

3) Rodar no Android

Com um emulador aberto (ou dispositivo via USB com depuração):

npx react-native run-android

Se der erro de device: confirme adb devices e se o emulador está “device” (não “offline”).

4) Rodar no iOS (macOS)

Em outro terminal:

npx react-native run-ios

Se o projeto usar CocoaPods e for necessário instalar dependências nativas (comum em projetos iOS), rode:

cd ios && pod install && cd ..

Depois tente novamente o run-ios.

5) Alterar um texto para validar Hot Reload/Fast Refresh

Abra o arquivo principal (geralmente App.tsx ou App.js), altere um texto e salve. O app deve atualizar automaticamente. Se não atualizar, verifique se o Metro está rodando e se o dispositivo está na mesma rede (no caso de device físico).

Primeiro teste com Expo (managed)

1) Criar o app

npx create-expo-app MeuAppExpo

cd MeuAppExpo

2) Rodar

npx expo start

Você poderá abrir no simulador/emulador (quando configurados) ou em dispositivo físico. Para validar especificamente Android e iOS localmente, use os atalhos do terminal do Expo (ele indica as teclas disponíveis) ou rode com flags conforme sua necessidade.

Validação mínima: o bundler inicia sem erros, o app abre no emulador/simulador e uma alteração em um componente reflete no app.

Organização de pastas do projeto gerado (o que observar)

Estrutura típica no React Native CLI

• android/: projeto Gradle, configurações de build, manifests, recursos nativos.
• ios/: projeto Xcode, configurações de assinatura, pods, assets nativos.
• App.js ou App.tsx: componente raiz.
• index.js: ponto de entrada que registra o app.
• package.json: scripts e dependências.
• metro.config.js (quando presente): ajustes do bundler Metro.
• babel.config.js: configuração do Babel.

Estrutura típica no Expo

• app/ (em templates com Expo Router) ou arquivos na raiz: telas/rotas e componentes.
• assets/: imagens, fontes.
• app.json ou app.config.js: configuração do app (nome, ícone, permissões via plugins).
• package.json: scripts e dependências.

Observação importante: no Expo managed, as pastas android/ e ios/ podem não existir inicialmente (dependendo do fluxo). No CLI, elas sempre existem porque o projeto já nasce “nativo”.

Como ler o output do Metro e do console

Metro (terminal do bundler)

• “Bundling…”: o Metro está empacotando o JS; em primeira execução pode demorar mais.
• Erros de módulo não encontrado: geralmente dependência não instalada ou caminho/import incorreto. Solução típica: instalar pacote e reiniciar Metro limpando cache.
• Cache: quando suspeitar de cache inconsistente, reinicie com reset:

npx react-native start --reset-cache

Logs do app (Android e iOS)

Além do console do Metro, é útil ver logs nativos:

• Android (Logcat): no Android Studio, abra Logcat e filtre pelo seu app.
• iOS: no Xcode, veja o console de execução do target.

No JavaScript, use console.log para validar fluxo:

console.log('Setup OK: app iniciou');

Se o app abre mas não carrega JS (tela branca), verifique: Metro rodando, dispositivo alcançando o bundler (rede), e se não há erro de bundle no terminal.