2. Configuração do ambiente de desenvolvimento
2.1. Instalação das ferramentas
- Node.js: baixe e instale a versão 24 (LTS) em nodejs.org. O [Angular CLI] 22 exige o [Node.js] 22.22.3 (ou uma versão 22 mais recente), 24.15 ou superior, ou 26 e posteriores: uma versão mais antiga não conseguirá executar o comando [ng]. O instalador também instala o [npm], o gerenciador de pacotes do [Node.js]. Verifique a instalação em um terminal:
-
Visual Studio Code ([VS Code]): disponível para download gratuito em code.visualstudio.com. Instale as extensões [Angular Language Service] (preenchimento automático e validação nos templates [HTML]) e [Ionic] (comandos para [Ionic] e [Capacitor] no editor). O suporte a [TypeScript] já está integrado ao [VS Code].
-
Chrome: o navegador usado para desenvolver a aplicação (google.com/chrome). Suas ferramentas de desenvolvedor (F12) exibem a aplicação no tamanho de um celular e também permitem depurar a aplicação instalada no celular (veja os apêndices).
-
MySQL 8 (ou MariaDB): necessário apenas para o servidor JSON. Instale-o, por exemplo, pelo Laragon (no [Windows]), pelo XAMPP, ou diretamente pelo MySQL Community Server. Uma ferramenta gráfica de administração ([HeidiSQL], [phpMyAdmin], [MySQL Workbench], [DBeaver]...) facilita o restante do processo. Este curso usa o [Laragon].
2.2. Instalação do cliente Ionic
Com o [Flutter], era preciso instalar um SDK: o framework, a linguagem [Dart] e suas ferramentas, comuns a todos os projetos. Com o [Ionic], não há nenhum SDK a instalar: [Angular], [Ionic], [Capacitor], o compilador [TypeScript] e suas ferramentas de linha de comando ([ng], [cap]) são simples pacotes [npm], declarados no arquivo [package.json] de cada projeto e instalados em sua pasta [node_modules/]. Cada projeto tem assim as suas próprias versões, e dois projetos podem usar versões diferentes do [Angular] sem interferir um no outro.
Instalar o cliente [Ionic] de um projeto significa, portanto, instalar seus pacotes. No [VS Code], abra a pasta do projeto (menu Arquivo / Abrir Pasta, por exemplo, a pasta [examples_ionic]), abra um console (menu Terminal / Novo Terminal) e digite:
Este comando baixa os pacotes descritos em [package.json] (com suas dependências: várias centenas de pacotes, totalizando algumas centenas de megabytes) nas versões exatas listadas em [package-lock.json]. Só é necessário executá-lo novamente se você adicionar um pacote ou alterar uma versão.
As ferramentas do projeto são então iniciadas por meio do [npx], que executa o comando de um pacote instalado no projeto (sem o [npx], o console procuraria um comando instalado em todo o sistema). O comando [npx ng version] verifica a instalação do [Angular]:
O resultado é parecido com este (aqui no [Linux]; no [Windows], a linha [Operating System] exibe [win32 x64]):
A coluna [Requested Version] lista as versões solicitadas pelo [package.json]; a coluna [Installed Version] lista as versões que o [npm] realmente instalou. As versões do [Ionic] e do [Capacitor] não aparecem nesta tabela, que é reservada aos pacotes do [Angular]; o comando [npm ls --depth=0] as lista todas. O comando [npx cap doctor] é o equivalente, para o [Capacitor], do [flutter doctor]:
O [Capacitor] compara as versões instaladas no projeto com as últimas versões publicadas. O pacote [@capacitor/ios] não está instalado: este curso se concentra apenas no [Android] (uma aplicação [iOS] é compilada em um [Mac], com o [Xcode]). Depois que o projeto [Android] for criado ([npx cap add android], veja o Exemplo 01), o comando também verifica esse projeto.
Resta apenas executar a aplicação no mesmo console:
em seguida, abra o endereço [http://localhost:8100] no [Chrome]: você verá o menu dos 25 exemplos (veja o Exemplo 01). Ao contrário do [Flutter], não há dispositivo a selecionar: no navegador, a aplicação é servida pelo [ng serve]; no [Android], ela é compilada e depois instalada pelo [Capacitor].
A ferramenta [@ionic/cli] (opcional). A equipe do [Ionic] também publica uma ferramenta de linha de comando, que é instalada em todo o sistema:
- Linha 1: instala o comando [ionic];
- linha 2: cria um novo projeto [Ionic] + [Angular] + [Capacitor] a partir de um modelo ([blank]: uma página em branco, [tabs]: abas, [sidemenu]: um menu lateral), fazendo algumas perguntas;
- linha 3: inicia o servidor de desenvolvimento (que por sua vez chama o [ng serve]);
- linha 4: compila a aplicação, instala-a em um dispositivo ([Android]), e a recarrega sempre que o código é modificado ([-l], “live reload”); [--external] faz o servidor de desenvolvimento escutar no endereço do computador na rede local, que o celular consegue alcançar.
Isso é apenas uma comodidade: o [ionic] simplesmente encadeia os comandos [ng] e [cap], e exige um arquivo [ionic.config.json] no projeto (que é criado pelo [ionic start], ou pelo [ionic init] para um projeto existente). Os projetos deste curso não têm esse arquivo: foram criados com [ng new] (veja o Exemplo 01), e usamos diretamente o [ng] e o [cap] , que fazem parte do projeto. Essa é a maneira mais direta de ver o que está acontecendo, e não depende de nenhuma ferramenta instalada no computador.
Descreveremos agora como instalar as ferramentas para desenvolver para [Android].
2.3. Android Studio e as ferramentas de linha de comando do Android
O dispositivo de destino deste curso é um celular [Android]. Para compilar a aplicação [Android] e instalá-la nesse celular, o [Capacitor] exige o SDK [Android], e um JDK (o compilador [Java], usado pela ferramenta de build [Gradle]), que são instalados junto com o [Android Studio], o ambiente de desenvolvimento do [Google]. [Android Studio] não é usado para escrever código (o editor continua sendo o [VS Code]): aqui ele serve para instalar e atualizar o SDK [Android], criar emuladores e, ocasionalmente, abrir o projeto [Android] criado pelo [Capacitor] ([npx cap open android]).
-
[Android Studio]: baixe-o gratuitamente em developer.android.com/studio, e depois instale-o. Ao iniciá-lo pela primeira vez, o assistente oferecerá uma instalação padrão: aceite-a, e ele baixará o SDK [Android].
-
Abra o [SDK Manager] a partir do [Android Studio] (menu [Tools / SDK Manager] quando um projeto está aberto, ou [More Actions / SDK Manager] na tela inicial): ele instala e atualiza os componentes do SDK [Android].
-
[SDK Platforms] aba: verifique se uma plataforma [Android] recente está instalada. O [Capacitor] 8 compila aplicações para a API 36 ([Android] 16);
-
[SDK Tools] aba: marque [Android SDK Build-Tools], [Android SDK Platform-Tools] (que contém o [adb], a ferramenta que conecta o computador ao dispositivo), [Android Emulator] (se quiser testar em um emulador) e [Android SDK Command-line Tools (latest)] (que inclui a ferramenta [sdkmanager]) e depois clique em [Apply].
-
Aceite as licenças do SDK [Android]: o [Android Studio] as aceita automaticamente a cada componente instalado. Se, mais tarde, o build da aplicação falhar por causa de uma licença não aceita, aceite todas elas com a ferramenta [sdkmanager] do pacote [Android SDK Command-line Tools], respondendo [y] a cada pergunta até aparecer a mensagem “All SDK package licenses accepted.” (no [Windows], no [PowerShell]):
-
JDK: o [Capacitor] 8 exige o JDK 21 ou posterior. Não é preciso instalar um: o [Android Studio] já vem com o seu próprio, o [JBR] (“JetBrains Runtime”), localizado em seu subdiretório [jbr]. Nas versões recentes do [Android Studio], trata-se de um [Java] 25: isso exige um pequeno ajuste no projeto [Android] gerado pelo [Capacitor] (atualização para o [Gradle] 9.1), como mostrado no Exemplo 01.
-
Variáveis de ambiente. [Capacitor] ([npx cap run android]) inicia por conta própria o build do [Gradle] e a ferramenta [adb]; ele precisa saber onde estão o SDK e o JDK. No [Windows], em Configurações / Sistema / Informações do Sistema / Configurações avançadas do sistema / Variáveis de Ambiente, crie duas variáveis de usuário:
-
[ANDROID_HOME]: a pasta do SDK [Android]; por padrão, [C:\Users\<name>\AppData\Local\Android\Sdk] (o [SDK Manager] a exibe no alto de sua janela, em [Android SDK Location]);
- [JAVA_HOME]: a pasta do JDK do [Android Studio]; por padrão, [C:\Program Files\Android\Android Studio\jbr].
Adicione também a pasta [%ANDROID_HOME%\platform-tools] à variável [Path] para poder digitar [adb] em um console. Se o [Android Studio] não estiver instalado no local padrão, o comando [npx cap open android] também exige a variável [CAPACITOR_ANDROID_STUDIO_PATH]: o caminho do programa [studio64.exe]. As novas variáveis só são visíveis para os consoles abertos depois de sua criação; é preciso reiniciar o [VS Code]. Verifique em um novo console:
2.4. Configurar um emulador Android
Se você não tem um celular, pode testar o aplicativo em um emulador [Android]: um celular virtual que roda em uma janela do computador. O [Android Studio] instala o programa [Android Emulator] (se ele foi marcado no [SDK Manager], veja acima), mas não fornece um dispositivo virtual pronto para uso: é preciso criar um.
- [Prerequisites]: a virtualização deve estar ativada na [BIOS] do computador e, no [Windows], o recurso [Windows Hypervisor Platform] deve estar marcado ([Control Panel / Programs / Turn Windows features on or off]), o que exige uma reinicialização. Caso contrário, o emulador não iniciará ou ficará muito lento;
- abra o [Device Manager] a partir do [Android Studio]: [More Actions / Virtual Device Manager] na tela inicial, ou [Tools / Device Manager] quando um projeto está aberto (dependendo da versão: [View / Tool Windows / Device Manager]);
- clique em [Create Device], selecione um modelo (por exemplo, [Pixel 8]) e depois em [Next]. Selecione uma imagem de sistema [Android], recente, para o processador [x86_64] e baixe-a pelo link [Download] ao lado dela; depois, [Next] e [Finish];
- inicie o emulador com o botão [Play] do [Device Manager];
- aguarde até que a tela de boas-vindas do [Android] apareça na janela do emulador: a primeira inicialização pode levar vários minutos.
Em seguida, verifique se o computador reconhece o emulador. Há dois comandos para isso:
- Linha 1: o [adb] lista os dispositivos conectados ao computador, um por linha: seu identificador (por exemplo, [emulator-5554] para o primeiro emulador) seguido de seu status, que deve ser [device];
- Linha 2: na pasta de um projeto [Capacitor] ([examples_ionic], por exemplo), o [Capacitor] lista os dispositivos nos quais pode instalar a aplicação: dispositivos conectados e em execução, bem como emuladores criados no [Android Studio], mesmo que estejam desligados (ele sabe iniciá-los). É o equivalente ao [flutter devices].
[Note]: se o [adb devices] exibir o emulador com o status [offline], o emulador não terminou de inicializar, ou o [adb] está em um estado inconsistente. Tente o seguinte, nesta ordem: (1) aguarde a tela de boas-vindas aparecer e execute o comando novamente; (2) reinicie o [adb] com os três comandos a seguir (no [Windows], no [PowerShell]); o último deve exibir [device] e não [offline]; (3) no [Device Manager], selecione [Cold Boot Now] no menu [⋮] do dispositivo ou, em último caso, [Wipe Data] .
Se o problema persistir, use [where.exe adb] para verificar se não há outro [adb], de uma versão diferente, no [Path]: duas versões do [adb] disputando a conexão causam esse problema.
Quando o emulador for reconhecido, a aplicação se instala nele e é iniciada com o comando a seguir, executado na pasta do projeto, depois de [npx ng build] e de [npx cap sync android] (veja o Exemplo 01); [--target] identifica o dispositivo pelo seu ID; caso contrário, o comando pede que você selecione um:
No emulador, o computador que o executa tem o endereço [10.0.2.2]: é aí que a aplicação procurará o servidor JSON (veja o Exemplo 22).
2.5. Preparação do celular Android
Para executar o aplicativo em um celular [Android] real, o celular deve ser configurado para ser controlado pelo computador:
- ative as opções do desenvolvedor: abra [Settings / About phone], e toque várias vezes (geralmente 7) em [Build number] até que o celular indique que você é um desenvolvedor. Os rótulos exatos variam conforme o fabricante;
- ative a [USB debugging] nas [Developer options] (menu adicionado na etapa anterior);
- conecte o celular ao computador com um cabo USB que transfira dados (e não apenas carregue o celular) e aceite, no celular, a solicitação de autorização de depuração USB. No [Windows], se o celular não for reconhecido, instale o driver USB do fabricante (“OEM USB drivers”, veja developer.android.com/studio/run/oem-usb);
- verifique se o computador detecta o celular: ele deve aparecer, com o status [device], na lista exibida por [adb devices] (o status [unauthorized] significa que a solicitação de autorização não foi aceita no celular) e na lista exibida por [npx cap run android --list].
O celular acessará o servidor [NestJS] pelo endereço IP do computador na rede local (e não por [localhost], que, do ponto de vista do celular, é o próprio celular): essa configuração é descrita no Exemplo 22 e no capítulo “Implantação”.