Skip to content

2. Configuração do ambiente de desenvolvimento

2.1. Instalação das ferramentas

  1. 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:
node --version
npm --version
  1. 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].

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

  3. 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:

npm install

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]:

npx ng version

O resultado é parecido com este (aqui no [Linux]; no [Windows], a linha [Operating System] exibe [win32 x64]):

     _                      _                 ____ _     ___
    / \   _ __   __ _ _   _| | __ _ _ __     / ___| |   |_ _|
   / △ \ | '_ \ / _` | | | | |/ _` | '__|   | |   | |    | |
  / ___ \| | | | (_| | |_| | | (_| | |      | |___| |___ | |
 /_/   \_\_| |_|\__, |\__,_|_|\__,_|_|       \____|_____|___|
                |___/

Angular CLI       : 22.2.1
Angular           : 22.2.1
Node.js           : 24.21.0
Package Manager   : npm 10.9.4
Operating System  : linux x64

┌───────────────────────────┬───────────────────┬───────────────────┐
│ Package                   │ Installed Version │ Requested Version │
├───────────────────────────┼───────────────────┼───────────────────┤
│ @angular/build            │ 22.2.1            │ ^22.2.1           │
│ @angular/cli              │ 22.2.1            │ ^22.2.1           │
│ @angular/common           │ 22.2.1            │ ^22.2.0           │
│ @angular/compiler         │ 22.2.1            │ ^22.2.0           │
│ @angular/compiler-cli     │ 22.2.1            │ ^22.2.0           │
│ @angular/core             │ 22.2.1            │ ^22.2.0           │
│ @angular/forms            │ 22.2.1            │ ^22.2.0           │
│ @angular/platform-browser │ 22.2.1            │ ^22.2.0           │
│ @angular/router           │ 22.2.1            │ ^22.2.0           │
│ rxjs                      │ 7.8.2             │ ~7.8.0            │
│ typescript                │ 6.0.3             │ ~6.0.2            │
└───────────────────────────┴───────────────────┴───────────────────┘

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]:

npx cap doctor
💊   Capacitor Doctor  💊

Latest Dependencies:

  @capacitor/cli: 8.5.2
  @capacitor/core: 8.5.2
  @capacitor/android: 8.5.2
  @capacitor/ios: 8.5.2

Installed Dependencies:

  @capacitor/ios: not installed
  @capacitor/cli: 8.5.2
  @capacitor/core: 8.5.2
  @capacitor/android: 8.5.2

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:

npm start

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:

1
2
3
4
npm install -g @ionic/cli
ionic start
ionic serve
ionic capacitor run android -l --external
  • 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]).

  1. [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].

  2. 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].

  3. [SDK Platforms] aba: verifique se uma plataforma [Android] recente está instalada. O [Capacitor] 8 compila aplicações para a API 36 ([Android] 16);

  4. [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].

  5. 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]):

& "$env:LOCALAPPDATA\Android\Sdk\cmdline-tools\latest\bin\sdkmanager.bat" --licenses
  1. 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.

  2. 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:

  3. [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]);

  4. [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:

adb version
& "$env:JAVA_HOME\bin\java" -version

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:

adb devices
npx cap run android --list
  • 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] .

1
2
3
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" kill-server
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" start-server
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" devices

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:

npx cap run android --target emulator-5554

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