Preparando o Ubuntu para desenvolver com React Native

Configurar o ambiente do React Native não é difícil, mas envolve várias peças: Node.js, Java, Android Studio, SDK, variáveis de ambiente e um emulador. Se uma delas ficar faltando, o primeiro build costuma responder com uma mensagem pouco amigável.

Este texto é minha versão prática do guia oficial de configuração do React Native, pensando em uma máquina com Ubuntu e no desenvolvimento para Android.

Não vamos configurar iOS porque o build nativo depende do macOS e do Xcode. No Ubuntu, nosso alvo será Android, usando um emulador ou um aparelho físico.

O que vamos instalar

No fim, o ambiente terá:

Git e ferramentas básicas de compilação;
Node.js 22 ou mais recente;
JDK 17;
Android Studio;
Android SDK, Build Tools e Platform Tools;
KVM para o emulador não se arrastar;
um projeto React Native rodando de verdade.

Eu prefiro fazer a configuração em blocos e testar cada ferramenta antes de seguir. É bem mais fácil descobrir onde algo deu errado.

1. Preparando o Ubuntu

Começamos atualizando a lista de pacotes e instalando algumas ferramentas que serão úteis durante a configuração:

code

sudo apt update
sudo apt install -y curl git unzip zip build-essential

Confirme o Git:

code

git --version

2. Instalando o Node.js com NVM

O React Native atualmente exige Node.js 22.11.0 ou superior. Como projetos diferentes podem pedir versões diferentes, uso NVM em vez de instalar Node diretamente pelo apt.

Se o NVM ainda não estiver instalado, deixei um passo a passo separado em Gerenciando múltiplas versões de Node.js com NVM.

Com o NVM disponível, instale a linha 22 e deixe-a como padrão:

code

nvm install 22
nvm alias default 22
nvm use 22

Confira as versões:

code

node -v
npm -v

Se o node -v mostrar uma versão igual ou superior à v22.11.0, podemos continuar.

3. Instalando o JDK 17

O Android usa Gradle para compilar o projeto nativo, e o Gradle precisa do Java. A recomendação atual do React Native é o JDK 17. Versões mais novas podem funcionar, mas também podem criar incompatibilidades desnecessárias.

No Ubuntu:

code

sudo apt install -y openjdk-17-jdk

Confirme:

code

java -version
javac -version

As duas respostas devem indicar a versão 17.

Agora adicione o JAVA_HOME ao final do ~/.bashrc:

code

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$PATH:$JAVA_HOME/bin"

Recarregue o terminal e confira o caminho:

code

source ~/.bashrc
echo $JAVA_HOME

Esse é o caminho padrão no Ubuntu para máquinas x86_64. Se ele não existir, use o comando abaixo para localizar a instalação ativa:

code

readlink -f $(which java)

O JAVA_HOME deve apontar para a pasta do JDK, sem o trecho /bin/java no final.

4. Instalando o Android Studio

Baixe a versão estável para Linux na página oficial do Android Studio. O arquivo vem como .tar.gz.

Depois do download, entre na pasta onde ele foi salvo e extraia o conteúdo:

code

cd ~/Downloads
tar -xzf android-studio-*-linux.tar.gz

Mova a pasta para /opt:

code

sudo mv android-studio /opt/android-studio

Abra o Android Studio:

code

/opt/android-studio/bin/studio.sh

No primeiro início, siga o assistente com a instalação padrão. Garanta que estes componentes estejam selecionados:

Android SDK;
Android SDK Platform;
Android Virtual Device.

Depois, dentro do Android Studio, use Tools → Create Desktop Entry se quiser criar um atalho no menu de aplicativos.

5. Instalando o SDK necessário

Na tela inicial do Android Studio, abra More Actions → SDK Manager. Se algum projeto já estiver aberto, o mesmo menu fica em Settings → Languages & Frameworks → Android SDK.

Na aba SDK Platforms:

marque Show Package Details;
expanda Android 15 (VanillaIceCream);
selecione Android SDK Platform 35;
selecione uma imagem de sistema Google APIs x86_64.

Na aba SDK Tools, marque Show Package Details e instale:

Android SDK Build-Tools 36.0.0;
Android SDK Command-line Tools (latest);
Android SDK Platform-Tools;
Android Emulator.

Clique em Apply e espere os downloads terminarem. Essa parte costuma ser a mais demorada.

As versões exigidas mudam com o React Native. Se estiver configurando outra versão do framework, vale conferir o compileSdk do projeto e a documentação atual antes de instalar tudo.

6. Configurando o ANDROID_HOME

No Ubuntu, o Android Studio normalmente salva o SDK em $HOME/Android/Sdk.

Adicione estas linhas ao final do ~/.bashrc:

code

export ANDROID_HOME="$HOME/Android/Sdk"
export PATH="$PATH:$ANDROID_HOME/emulator"
export PATH="$PATH:$ANDROID_HOME/platform-tools"

Recarregue a configuração:

code

source ~/.bashrc

Agora verifique cada parte:

code

echo $ANDROID_HOME
adb version
emulator -version

Se o caminho do SDK for diferente, o local correto aparece no próprio SDK Manager, no campo Android SDK Location. É melhor copiar esse caminho do que tentar adivinhar.

7. Ativando a aceleração do emulador

Sem aceleração por hardware, o emulador Android pode ficar muito lento. No Linux, ele usa KVM.

Primeiro, veja se o processador possui virtualização:

code

sudo apt install -y cpu-checker
kvm-ok

O resultado esperado é algo parecido com:

code

INFO: /dev/kvm exists
KVM acceleration can be used

Se a virtualização estiver desativada, será necessário habilitar Intel VT-x ou AMD-V na BIOS/UEFI.

Instale o KVM e os pacotes de suporte:

code

sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils
sudo adduser "$USER" kvm
sudo adduser "$USER" libvirt

Depois, encerre a sessão do Ubuntu e entre novamente para atualizar os grupos do usuário. Reiniciar a máquina também resolve.

O guia de aceleração do Android Emulator tem mais detalhes para casos em que o kvm-ok continua falhando.

8. Criando um dispositivo virtual

No Android Studio, abra More Actions → Virtual Device Manager e escolha Create Virtual Device.

Para uma configuração simples:

escolha um aparelho da categoria Phone, como um Pixel;
selecione a imagem do Android 15, API 35, com Google APIs;
mantenha as opções padrão;
finalize e inicie o aparelho pelo botão de execução.

Espere o Android terminar de iniciar e confirme que o ADB consegue encontrá-lo:

code

adb devices

A saída deve mostrar um dispositivo com estado device:

code

List of devices attached
emulator-5554    device

9. Criando o primeiro projeto

Evite instalar react-native-cli globalmente. A CLI global antiga pode entrar em conflito com a versão usada pelo projeto.

Se ela já estiver instalada, remova:

code

npm uninstall -g react-native-cli @react-native-community/cli

Crie um projeto novo usando a Community CLI:

code

npx @react-native-community/cli@latest init MeuPrimeiroApp
cd MeuPrimeiroApp

Com o emulador aberto, inicie o Metro:

code

npm start

Deixe esse terminal rodando. Em outro terminal, entre na pasta do projeto e execute:

code

npm run android

O primeiro build demora porque o Gradle precisa baixar dependências. Os próximos tendem a ser bem mais rápidos.

Se tudo estiver certo, o app padrão aparecerá no emulador. Nesse ponto, o ambiente está pronto.

Erros que costumo conferir primeiro

`SDK location not found`

Confira se ANDROID_HOME aponta para a pasta exibida no SDK Manager:

code

echo $ANDROID_HOME
ls $ANDROID_HOME

`adb: command not found`

Recarregue o shell e confirme se platform-tools entrou no PATH:

code

source ~/.bashrc
which adb

Nenhum dispositivo encontrado

Abra o emulador antes do build e rode:

code

adb kill-server
adb start-server
adb devices

Erro relacionado ao Java ou Gradle

Confirme que o terminal e o Gradle estão usando o JDK 17:

code

java -version
echo $JAVA_HOME
cd android && ./gradlew --version

`ENOSPC` durante o Metro

No Linux, essa mensagem muitas vezes significa que o limite de arquivos observados foi atingido, não que o disco ficou sem espaço. Aumente o limite temporariamente:

code

sudo sysctl fs.inotify.max_user_watches=524288

Se o erro desaparecer, aí vale tornar a configuração permanente no sistema.

Checklist final

Antes de considerar o ambiente pronto, estes comandos precisam funcionar:

code

node -v
npm -v
java -version
echo $JAVA_HOME
echo $ANDROID_HOME
adb version
emulator -version
adb devices

No fim, o React Native em si é a parte rápida. O trabalho maior é deixar Node, Java e Android SDK conversando corretamente. Depois que isso está organizado, criar ou clonar um projeto novo deixa de ser uma aventura.

Fechamento

Ter esse passo a passo salvo evita repetir a mesma pesquisa sempre que preciso configurar uma máquina ou entender por que um build Android não inicia. O ponto principal é validar cada camada separadamente: primeiro Node, depois Java, SDK, ADB e emulador.

Quando todos os comandos do checklist respondem corretamente, qualquer erro seguinte tende a estar no projeto, não no ambiente. Essa separação já economiza um bom tempo de investigação.

O que vamos instalar

1. Preparando o Ubuntu

2. Instalando o Node.js com NVM

3. Instalando o JDK 17

4. Instalando o Android Studio

5. Instalando o SDK necessário

6. Configurando o ANDROID_HOME

7. Ativando a aceleração do emulador

8. Criando um dispositivo virtual

9. Criando o primeiro projeto

Erros que costumo conferir primeiro

SDK location not found

adb: command not found

Nenhum dispositivo encontrado

Erro relacionado ao Java ou Gradle

ENOSPC durante o Metro

Checklist final

Fechamento

Referências

`SDK location not found`

`adb: command not found`

`ENOSPC` durante o Metro