Aula Interativa • Do Web App ao APK com Capacitor e GitHub Actions

ETAPA 1 DE 9

Entendendo a Arquitetura: Da Web ao Nativo

Como o Capacitor e a Nuvem resolvem o problema de peso do Android Studio.

A Grande Analogia Visual

A Ponte (Capacitor) conectando a Ilha Web ao Mundo Mobile

A Analogia do Chassi de Carro 🏎️

Imagine que o seu código HTML, CSS e JavaScript é o motor e o interior luxuoso de um veículo. Ele já é bonito e funcional.

O Capacitor é o chassi nativo de alta tecnologia que envelopa seu motor. Ele permite que o seu carro ande nas rodovias oficiais do Android (Google Play) e do iOS (App Store) sem que você precise reescrever o motor do zero em Kotlin ou Java!

Ação Prática Obrigatória: Criar a pasta "www"

Antes de qualquer comando, crie a pasta www na raiz do seu projeto e mova seu index.html (e pastas de estilo/imagens) para dentro dela:

Criar pasta no terminal

mkdir www

Como seu projeto deve ficar:

meu-projeto/

└── www/

├── index.html (site principal)

├── style.css

└── js/ ou data/

Jeito Antigo / Tradicional

• Instalar Android Studio (+10 GB de disco)
• Consome 8 a 16 GB de RAM durante o build
• Configurar variáveis de ambiente PATH, JAVA_HOME
• Travamento em computadores de alunos

Nosso Método Moderno (Nuvem)

• O computador do aluno fica 100% leve
• O Capacitor gera a pasta nativa em segundos
• Os supercomputadores do GitHub compilam tudo
• Você só faz o download do arquivo .apk pronto!

ETAPA 2 DE 9

Inicializando o Node.js (`npm init`)

Transformando seu diretório simples em um projeto Node reconhecido.

Analogia do Passaporte / Certidão

A Identidade Oficial do Projeto 📄

Antes de viajar e receber ferramentas internacionais (como o Capacitor), o seu projeto precisa de um Passaporte Oficial.

O comando npm init -y emite o package.json, registrando o nome do seu projeto, autor e a lista de ferramentas instaladas.

Terminal (na pasta do projeto)

npm init -y

💡 O que o parâmetro -y significa? Significa "yes to all". Ele aceita todas as perguntas padrão de criação automaticamente sem que o aluno precise apertar Enter 10 vezes.

ETAPA 3 DE 9

Instalar Capacitor Core & CLI

Adicionando as ferramentas que criam a ponte nativa.

Analogia do Tradutor Universal

O Tradutor Bilíngue (Web ↔ Nativo) 🌐

O navegador fala JavaScript; o celular Android fala Java/Kotlin.

O @capacitor/core é o tradutor simultâneo que permite que um clique em um botão HTML acione a vibração do celular, acesse a câmera ou abra o teclado nativo. A CLI é a caixa de ferramentas que executa essas criações.

Terminal

npm install @capacitor/core @capacitor/cli --save-dev

ETAPA 4 DE 9

Configurar o Aplicativo (`npx cap init`)

Definindo nome, ID único de pacote e a pasta de arquivos web (www).

Analogia da Planta Baixa

A Certidão de Registro do App 🏠

Assim como uma casa precisa de endereço e planta aprovada, o Android exige saber:

Nome Público: "Toco e Teco" (aparece embaixo do ícone no celular).
App ID: com.tocoteco.brinquedos (identificador único mundial).
Onde estão os arquivos web: --web-dir "www" (a pasta onde está seu index.html).

⚠️ Atenção com a pasta www (Evite erro do ponto "."):

O Capacitor proíbe usar "." (a raiz). Coloque seus arquivos do site (HTML, CSS, JS) dentro da pasta www e use sempre --web-dir "www".

Terminal

npx cap init "Toco e Teco" "com.tocoteco.brinquedos" --web-dir "www"

Resultado: criação do capacitor.config.json:

{
  "appId": "com.tocoteco.brinquedos",
  "appName": "Toco e Teco",
  "webDir": "www",
  "bundledWebRuntime": false
}

ETAPA 5 DE 9

Adicionar Plataforma Android & Sincronizar

Gerando a pasta nativa android/ e transportando os arquivos da pasta www/.

Analogia da Esteira de Encomendas

A Esteira de Carga (Sync) 📦

1. npx cap add android constrói o hangar do avião (a pasta android/ nativa com Gradle).

2. npx cap sync android é a esteira rolante que pega os arquivos de www/ e coloca no compartimento de carga do Android para gerar o APK.

Terminal

npm install @capacitor/android
npx cap add android
npx cap sync android

ETAPA 6 DE 9

Criar o Arquivo `.gitignore`

Evitando o envio de arquivos desnecessários e pesados para o GitHub.

Analogia da Balança de Aeroporto

Viajando Leve (Sem Excesso de Bagagem) ✈️

A pasta node_modules/ pesa centenas de Megabytes com milhares de arquivinhos temporários.

O arquivo .gitignore é o filtro de segurança que diz ao Git: "Não gaste internet subindo isso; a nuvem do GitHub instalará tudo do zero quando for compilar!"

Conteúdo do arquivo .gitignore

node_modules/
.DS_Store
Thumbs.db
*.log

ETAPA 7 DE 9

Configurar o Robô na Nuvem (GitHub Actions)

A esteira automatizada que compila o APK nos servidores do GitHub.

Analogia da Fábrica 100% Automatizada

A Fábrica dos Robôs na Nuvem 🤖

Em vez de você forçar o seu computador local a compilar o Android, você entrega a "receita do bolo" (build-apk.yml) para o GitHub.

O GitHub liga um servidor Linux de alta performance, baixa o Java 17, instala as dependências, roda o Gradle e entrega o APK empacotado na sua mão!

Criar em: .github/workflows/build-apk.yml

name: Construir APK Android (Capacitor)

on:
  push:
    branches:
      - main
      - master
  workflow_dispatch:

jobs:
  build:
    name: Gerar APK de Depuracao (Debug)
    runs-on: ubuntu-latest

    steps:
      - name: 📥 Clonar Repositorio
        uses: actions/checkout@v4

      - name: 🟢 Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: 📦 Instalar Dependencias
        run: npm install

      - name: ☕ Configurar Java JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'

      - name: 🔄 Sincronizar Capacitor com Android
        run: npx cap sync android

      - name: 🔑 Permissao de Execucao do Gradle
        run: chmod +x android/gradlew

      - name: 🔨 Compilar APK com Gradle
        run: |
          cd android
          ./gradlew assembleDebug

      - name: 📤 Publicar APK para Download
        uses: actions/upload-artifact@v4
        with:
          name: meu-aplicativo-apk
          path: android/app/build/outputs/apk/debug/app-debug.apk

ETAPA 8 DE 9

Enviar o Código para o GitHub (Git Push)

Disparando a ordem de compilação automática.

Analogia da Ordem de Produção

Disparando o Gatilho da Fábrica 🚀

Ao rodar git push, seus arquivos chegam aos servidores do GitHub.

O GitHub percebe a chegada do novo código e aciona imediatamente o workflow que configuramos no passo anterior.

Comandos no Terminal

# 1. Se for a primeira vez usando Git no PC, configure seu nome e e-mail:
# git config --global user.name "Seu Nome"
# git config --global user.email "seu-email@exemplo.com"

git init
git add .
git commit -m "feat: configurando capacitor e build apk na nuvem"
git branch -M main
git remote add origin https://github.com/SEU_USUARIO/SEU_REPOSITORIO.git
git push -u origin main

ETAPA 9 DE 9

Baixar e Instalar o APK no Celular

Recebendo o arquivo final gerado com sucesso.

Analogia da Entrega da Encomenda

A Caixa Pronta para Usar 🎁

Na aba Actions do seu repositório no GitHub:

Clique no workflow concluído com ícone verde (✅).
Role até o rodapé na seção Artifacts.
Clique em meu-aplicativo-apk para baixar o .zip com o APK!
Envie para o celular (via WhatsApp/Drive) e instale!

Checklist do Aluno

Inicializei o package.json com npm init -y Instalei @capacitor/core e @capacitor/cli Configurei o nome e ID com npx cap init Adicionei a plataforma Android com npx cap add android Criei o arquivo .gitignore ignorando node_modules/ Criei o fluxo .github/workflows/build-apk.yml Enviei com git push e baixei o APK na aba Actions!

Entendendo a Arquitetura: Da Web ao Nativo

A Analogia do Chassi de Carro 🏎️

Jeito Antigo / Tradicional

Nosso Método Moderno (Nuvem)

Inicializando o Node.js (`npm init`)

A Identidade Oficial do Projeto 📄

Instalar Capacitor Core & CLI

O Tradutor Bilíngue (Web ↔ Nativo) 🌐

Configurar o Aplicativo (`npx cap init`)

A Certidão de Registro do App 🏠

Adicionar Plataforma Android & Sincronizar

A Esteira de Carga (Sync) 📦

Criar o Arquivo `.gitignore`

Viajando Leve (Sem Excesso de Bagagem) ✈️

Configurar o Robô na Nuvem (GitHub Actions)

A Fábrica dos Robôs na Nuvem 🤖

Enviar o Código para o GitHub (Git Push)

Disparando o Gatilho da Fábrica 🚀

Baixar e Instalar o APK no Celular

A Caixa Pronta para Usar 🎁

Checklist do Aluno

Parabéns! Aula Concluída 🚀