📚 Módulo 10: Mobile - Setup do Capacitor no Vue 3, Android Studio e Build Nativa

Neste módulo, daremos o primeiro passo para a expansão móvel da nossa TecLoja 02. Utilizaremos o Capacitor para empacotar a nossa SPA (Single Page Application) desenvolvida em Vue 3 + Vite e transformá-la em um aplicativo nativo Android totalmente funcional, sem reescrever o código de apresentação.

Configuraremos o ambiente móvel local, integraremos a CLI do Capacitor à nossa esteira de build do Vite e geraremos uma versão executável no emulador do Android Studio.

🗺️ 1. Arquitetura Híbrida com Capacitor

Abaixo, revisamos visualmente como o Capacitor faz a ponte entre o motor web da nossa SPA e a camada nativa do sistema operacional Android:

flowchart TD
    %% Styling
    classDef vue fill:#41B883,stroke:#35495E,stroke-width:2px,color:#fff;
    classDef cap fill:#1197F6,stroke:#0B5899,stroke-width:2px,color:#fff;
    classDef native fill:#3DDC84,stroke:#073042,stroke-width:2px,color:#fff;
    classDef backend fill:#009688,stroke:#00796B,stroke-width:2px,color:#fff;

    subgraph Vue_App ["📱 Camada Frontend (Web View)"]
        A[Vue 3 SPA - Vite Build]:::vue --> B[Capacitor Bridge]:::cap
    end

    subgraph Native_OS ["🤖 Camada Nativa (Android)"]
        B <-->|JavaScript Plugins Bridge| C[Capacitor Android Core]:::cap
        C <--> D[Atividades & Recursos OS]:::native
    end

    subgraph Server_API ["⚙️ Camada API Backend"]
        A <-->|HTTP / JWT Bearer| E[API FastAPI no Render]:::backend
    end

⚙️ 2. Instalação e Inicialização do Capacitor

Para iniciar a ponte móvel híbrida, acesse a pasta raiz do seu repositório frontend (tecloja-frontend) e instale o core do Capacitor e o suporte nativo ao ecossistema Android:

# 1. Instalar as dependências do Capacitor como dependências de desenvolvimento
npm install @capacitor/core
npm install -D @capacitor/cli @capacitor/android

Após instalar os pacotes, inicialize as configurações globais do Capacitor. O comando solicitará o nome do aplicativo e o ID de pacote exclusivo (Package ID / Application ID):

npx cap init

Durante o prompt de inicialização, responda de forma coerente com a nomenclatura e domínio de sua aplicação:

Após finalizar, um arquivo capacitor.config.json ou capacitor.config.ts será gerado automaticamente na raiz. Vamos configurá-lo para apontar corretamente para os assets compilados:

Configurando o capacitor.config.ts

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.tecloja.tecloja02',
  appName: 'TecLoja 02',
  webDir: 'dist',
  server: {
    androidScheme: 'https'
  }
};

export default config;

🏗️ 3. Sincronização e Geração do Projeto Android

Antes de sincronizar a aplicação com o framework nativo, precisamos gerar a pasta dist compilada para produção através do bundler Vite. A cada nova alteração de interface Web, você deverá reexecutar estes dois passos:

# 1. Compilar os assets estáticos do Vue 3 para produção
npm run build

# 2. Adicionar a plataforma Android ao Capacitor (apenas na primeira execução)
npx cap add android

Este comando criará um subdiretório nativo /android/ no seu projeto. Esse diretório é um projeto Android real baseado em Gradle que pode ser aberto e compilado diretamente no Android Studio.

Para transferir o código compilado da pasta /dist/ para a pasta de assets nativos do Android de forma contínua, rode:

npx cap sync

📱 4. Configurando e Executando no Android Studio

  1. Baixe e instale o Android Studio.
  2. Abra o projeto do Capacitor executando a CLI no terminal do frontend: 
    npx cap open android
  3. O Android Studio abrirá importando o projeto /android automaticamente. Aguarde até que o Gradle sincronize os índices do projeto.
  4. No menu superior, vá em Tools -> Device Manager e configure um dispositivo emulado (AVD), escolhendo uma versão recente do Android (API 33+ recomendada).
  5. Clique no botão Run (Play) no topo do Android Studio. O projeto compilará o APK local e abrirá a nossa aplicação Vue 3 simulada diretamente na tela do dispositivo emulado.

✅ Pré-Requisitos deste Módulo

Antes de iniciar este módulo, verifique se:

🤔 Por que fizemos assim?

🔍 Checkpoint

  1. Geração do build local: Certifique-se de que a execução do npm run build gera a pasta /dist/ sem dependências globais órfãs.
  2. Sincronização correta: Valide se o comando npx cap sync exibe a mensagem de sucesso para a plataforma Android.
  3. App no Emulador: Com o emulador Android de teste ativo, confirme se a página de login da TecLoja 02 renderiza e se você consegue fazer requisições à API remota (configurada em produção no Render).

⚠️ Erros Comuns

Erro Causa Solução
ERR_CLEARTEXT_NOT_PERMITTED ao bater na API local O app no emulador Android está tentando se conectar a uma URL http://localhost:8000 ou http://127.0.0.1:8000. O emulador não reconhece localhost como a sua máquina. Mude a URL da API para http://10.0.2.2:8000 (IP especial de loopback do emulador do Android) ou aponte para a URL de produção na Render com HTTPS.
O emulador abre uma tela em branco no carregamento inicial O caminho físico para os arquivos compilados no capacitor.config.ts está incorreto ou a pasta dist ainda não foi criada. Rode npm run build no console de desenvolvimento antes de disparar o comando npx cap sync.
Falha ao abrir no Android Studio: SDK location not found A variável local informando o caminho do Android SDK não está configurada no projeto nativo. Crie um arquivo chamado local.properties dentro da subpasta /android/ e adicione o caminho do seu SDK (ex: sdk.dir=C\:\\Users\\SeuUsuario\\AppData\\Local\\Android\\Sdk).

Voltar para o Sumário