Étape 27 — Installation Capacitor et build Android

Accessible à tout le monde

Cette étape fonctionne sur Windows, macOS et Linux. C'est le point de départ recommandé pour transformer votre Pokédex Vuetify en application mobile.

Temps estimé

Environ 1h pour la première fois (dont 20-30 min de téléchargement Android Studio + Gradle au premier build). Les fois suivantes : 5-10 min.

Pourquoi Capacitor ?

Votre Pokédex Vuetify est une web app. Avec Capacitor (créé par Ionic), on peut l'emballer dans une application native iOS et Android, publiable sur l'App Store et le Play Store, sans réécrire le code Vue.

Capacitor en une phrase

Capacitor crée un projet Gradle (Android) et un projet Xcode (iOS) qui contiennent une WebView native chargeant votre bundle Vite. La partie Vue/Vuetify reste identique.

	Web app	PWA	Capacitor
Accessible navigateur	Oui	Oui	Non
Installable sur écran d'accueil	Non	Oui	Oui
Publiable sur App Store / Play Store	Non	Non	Oui
Accès API natives (caméra, contacts...)	Non	Partiel	Oui
Réécriture du code	—	Léger	Aucune

Pré-requis (à installer AVANT de commencer)

1. Le projet Pokédex Vuetify fonctionnel

npm run dev doit afficher une page d'accueil avec la liste de Pokémon. Si ce n'est pas le cas, revenez aux étapes E1 à E24 ou clonez directement le code solution :

git clone -b magasin-API-2026 https://github.com/divtec-cejef/2024-SFA-TTI-JS-Vue-Vuetify-Pokedex.git pokedex-solution
cd pokedex-solution
npm install
npm run dev   # → vérifier la page d'accueil avant de continuer

2. Android Studio

Téléchargez depuis developer.android.com/studio (~1 Go, gratuit). Au premier lancement, l'assistant installe :

• Le SDK Android (~3 Go)
• Une image d'émulateur par défaut
• Les outils ligne de commande (adb, emulator)

Acceptez toutes les licences quand demandé.

3. JDK 21 (obligatoire pour Capacitor 7)

Le JDK fourni par défaut avec Android Studio est en 17 — il ne suffit pas. Installez JDK 21 :

Windows

# Avec winget (Windows 10+)
winget install EclipseAdoptium.Temurin.21.JDK

# OU télécharger manuellement le .msi depuis :
# https://adoptium.net/temurin/releases/?version=21

macOS

brew install openjdk@21

Linux

sudo apt install openjdk-21-jdk
# Ou suivez les instructions de votre distribution

4. Configurer JAVA_HOME de façon permanente

Sans cette variable, gradlew utilisera le JDK par défaut de votre système (souvent 17) et plantera avec error: invalid source release: 21.

Windows — Variables d'environnement

# Méthode interface :
# 1. Menu Démarrer → "Modifier les variables d'environnement système"
# 2. Cliquer "Variables d'environnement..."
# 3. Variables système → Nouvelle :
#    Nom : JAVA_HOME
#    Valeur : C:\Program Files\Eclipse Adoptium\jdk-21.0.x-hotspot
# 4. Sélectionner Path → Modifier → Nouveau → %JAVA_HOME%\bin
# 5. OK, OK, OK
# 6. FERMER et REOUVRIR tous les terminaux PowerShell ouverts

# Vérifier dans un nouveau terminal
java -version    # → openjdk version "21..."

macOS — ~/.zshrc

# Ajouter ces 2 lignes à la fin de ~/.zshrc
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

# Recharger
source ~/.zshrc

# Vérifier
java -version    # → openjdk version "21..."

Linux — ~/.bashrc

echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
java -version

5. Créer un AVD (Android Virtual Device)

Dans Android Studio :

1. Menu Tools → Device Manager (ou icône téléphone dans la barre latérale droite)
2. Cliquer Create Virtual Device
3. Catégorie Phone → choisir Pixel 7 (ou Medium Phone)
4. Cliquer Next
5. Système → onglet Recommended → choisir une image API 34 ou 35 (Android 14/15)
   • Si pas téléchargée : cliquer la flèche ↓ à côté du nom (téléchargement ~1 Go)
6. Next → laisser les options par défaut → Finish

Vous avez maintenant un AVD nommé par exemple Pixel 7 API 34. Cliquez sur le bouton ▶ pour le lancer (il apparaîtra dans une fenêtre séparée).

Émulateur lent ?

Sur Mac M1/M2/M3 : choisissez une image arm64-v8a (plus rapide que x86_64). Sur Windows/Linux Intel/AMD : choisissez x86_64 et activez l'accélération matérielle dans le BIOS (Intel VT-x / AMD-V).

Tâches

1. Installer Capacitor

Dans le dossier de votre projet :

# Le CLI Capacitor en dépendance de développement
npm install --save-dev @capacitor/cli@^7.2.0

# Le coeur + les plateformes iOS et Android
npm install --save @capacitor/core@^7.2.0 @capacitor/ios@^7.2.0 @capacitor/android@^7.2.0

Pourquoi installer aussi @capacitor/ios ?

Même sur Windows, il est inoffensif de l'installer — c'est juste un package npm. Le code natif iOS n'est utilisé que sur Mac (voir étape E28). L'installer dès maintenant évite des soucis si vous passez plus tard sur un Mac.

2. Pointer l'API vers la version en ligne

Une app mobile ne peut pas appeler http://localhost:3535 directement (l'émulateur Android ne voit pas le localhost du PC). Pour une app vraiment utilisable, on pointe vers l'API en ligne déployée sur Vercel.

src/plugins/axios.js

import axios from 'axios'

// URL de l'API : Vercel par défaut (utilisable depuis le web ET les apps mobiles
// iOS/Android compilées via Capacitor). Pour passer en local, définir
// VITE_API_URL=http://localhost:3535 dans un fichier .env.local
const API_BASE_URL = import.meta.env.VITE_API_URL || 'https://2025-sfa-pokedex-api.vercel.app'

axios.defaults.baseURL = API_BASE_URL
// ...

3. Créer le fichier de configuration Capacitor

À la racine du projet, créer capacitor.config.ts :

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

const config: CapacitorConfig = {
  appId: 'ch.divcom.pokedex',
  appName: 'Pokédex',
  webDir: 'dist',
  // Couleur de fond de la WebView (visible derrière le contenu pendant
  // le chargement). Doit matcher le fond du thème Vuetify dark.
  backgroundColor: '#121212',
  ios: {
    // 'never' : la WebView s'étend SOUS la status bar (utile pour le notch).
    contentInset: 'never',
  },
}

export default config

Choix de l'appId

Format inversé du nom de domaine : ch.divcom.pokedex. Il sert d'identifiant unique sur l'App Store et le Play Store, ne peut plus être changé une fois publié. Pas d'underscores, pas de tirets, pas de chiffres au début d'un segment.

4. Builder le bundle web

Capacitor copie le contenu de dist/ (généré par Vite) dans le projet natif. Il faut donc builder avant d'ajouter la plateforme :

npm run build

5. Ajouter la plateforme Android

npx cap add android

Cette commande crée le dossier android/ contenant un projet Gradle complet :

android/
├── app/
│   ├── build.gradle          ← config du module app
│   ├── src/main/
│   │   ├── AndroidManifest.xml
│   │   ├── assets/public/    ← votre bundle Vite copié
│   │   ├── java/ch/divcom/pokedex/MainActivity.java
│   │   └── res/              ← icônes, splash screen
│   └── ...
├── build.gradle              ← config racine Gradle
├── gradlew                   ← script Unix (Mac/Linux)
├── gradlew.bat               ← script Windows
└── settings.gradle

6. Builder l'APK debug

Deux façons :

Windows

cd android
.\gradlew.bat assembleDebug

# → génère app\build\outputs\apk\debug\app-debug.apk

Mac / Linux

cd android
./gradlew assembleDebug

# → génère app/build/outputs/apk/debug/app-debug.apk

Android Studio (toutes plateformes)

1. npx cap open android
2. Android Studio s'ouvre sur le projet
3. Attendre la fin du Gradle Sync (barre de progression en bas)
4. Build → Make Project (Cmd/Ctrl + F9)

Premier build = 5-15 minutes

Le premier assembleDebug télécharge Gradle (~150 Mo) et les dépendances Android. Si vous voyez la barre s'arrêter ou des "Downloading...", c'est normal. Les builds suivants prennent 20-30 secondes.

7. Lancer l'app sur l'émulateur

L'émulateur doit déjà être démarré (voir Pré-requis §5).

Android Studio (le plus simple)

1. Dans la barre du haut, à droite, vérifier que l'AVD est sélectionné
2. Cliquer le bouton ▶ vert (Run 'app')
3. Le build se lance, l'app est installée et démarrée automatiquement

Ligne de commande

# Installer (ou réinstaller : flag -r)
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# L'app apparaît dans le launcher de l'émulateur.
# Cliquer sur l'icône "Pokédex" pour la lancer.

8. Vérifier le résultat

L'app Pokédex s'ouvre, le titre s'affiche, la liste se charge depuis Vercel.

Réseau dans l'émulateur Android

L'émulateur Android ne voit pas localhost (qui pointerait vers lui-même). Si vous voulez tester avec une API locale, utilisez 10.0.2.2 (alias spécial vers le host) :

# Créer .env.local à la racine du projet
VITE_API_URL=http://10.0.2.2:3535

Puis npm run build && npx cap sync android et réinstaller l'APK.

Tests à effectuer

• L'APK se construit sans erreur (BUILD SUCCESSFUL)
• L'émulateur démarre et l'app apparaît dans le launcher
• La liste de Pokémon se charge (vient de Vercel — vérifier que vous êtes en ligne)
• Les images des Pokémon s'affichent
• La recherche fonctionne
• Le bouton retour Android (geste) revient à l'écran précédent

Erreurs courantes

Message d'erreur	Cause	Solution
error: invalid source release: 21	JDK 17 utilisé au lieu de 21	Vérifier JAVA_HOME (Pré-requis §4), réouvrir le terminal
JAVA_HOME is not set	Variable d'environnement absente	Voir Pré-requis §4 selon votre OS
SDK location not found	local.properties manquant dans android/	Ouvrir le projet une fois dans Android Studio, il génère le fichier
Could not resolve all dependencies (Gradle)	Pas de connexion internet au premier build	Connecter internet, relancer
INSTALL_FAILED_INSUFFICIENT_STORAGE	Émulateur saturé	Device Manager → Wipe Data sur l'AVD
more than one device/emulator	Plusieurs devices connectés	adb devices puis adb -s emulator-5554 install -r app-debug.apk
Émulateur ne démarre pas (Windows)	Hyper-V désactivé	Activer "Hyper-V" et "Windows Hypervisor Platform" dans les fonctionnalités Windows
Émulateur très lent	Pas d'accélération matérielle	BIOS → activer Intel VT-x / AMD-V

Pièges connus

Connexion internet requise

L'app utilise l'API Vercel en ligne. Sans internet, la liste sera vide et vous verrez des erreurs réseau dans la console.

Plusieurs devices connectés

Si vous avez un téléphone Android branché en USB et un émulateur lancé, adb install échouera. Préfixez avec -s <serial> :

adb devices                # voir la liste
adb -s emulator-5554 install -r android/app/build/outputs/apk/debug/app-debug.apk

Commit

git add -A
git commit -m "feat(mobile): ajout Capacitor et plateforme Android"

Suite

L'app marche sur Android, mais le header desktop est toujours là (taille pleine, liens visibles), ce qui n'est pas optimal sur mobile. Avant d'attaquer iOS (E26) ou les adaptations UI (E27), continuez selon votre plateforme :

• Sur Mac uniquement : étape E28 — Build iOS pour packager aussi pour iPhone
• Sur Windows / Linux : passez directement à étape E29 — Adaptations UI mobile