thats-me/frontend/MOBILE-APPS.md

Mobile Apps – iOS & Android

Die "Thats Me" App wird mit Capacitor (v7) als native iOS- und Android-App verpackt. Capacitor bündelt die Quasar Web-App in eine WebView innerhalb einer nativen App-Shell.

---

Wichtig: Zwei Umgebungen

Umgebung	Zweck
Docker-Container	Quasar Dev-Server, Vue-Code bearbeiten, npm install, Web-Entwicklung
Mac Server / Host	Xcode, CocoaPods, Capacitor-Builds, iOS Simulator

Xcode und CocoaPods laufen ausschließlich auf dem Mac (außerhalb Docker). Die installierten Tools auf dem Mac-Host beeinflussen den Docker-Container nicht – beide Umgebungen sind vollständig isoliert.

---

Projektstruktur

frontend/
├── src/                          # Quasar Quellcode (Vue.js)
├── src-capacitor/                # Capacitor nativer Wrapper
│   ├── ios/                      # Xcode-Projekt (lokal, nicht im Git)
│   ├── android/                  # Android Studio Projekt (lokal, nicht im Git)
│   ├── www/                      # Kompilierte Web-Assets (nicht im Git)
│   ├── capacitor.config.json     # App-Konfiguration
│   └── package.json              # Capacitor Dependencies
└── quasar.config.js              # Quasar Config

App-Konfiguration

Eigenschaft	Wert
App ID	media.adametz.thatsme
App Name	Thats Me

---

Einmaliges Setup auf dem Mac

1. Voraussetzungen installieren

# Homebrew (falls nicht vorhanden)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js
brew install node

# CocoaPods (iOS Dependency Manager)
brew install cocoapods
# oder: sudo gem install cocoapods

# Prüfen:
node --version   # z.B. v25.x
pod --version    # z.B. 1.16.2

2. Xcode einrichten

• Xcode aus dem Mac App Store installieren (~15 GB, etwas Geduld)
• Nach der Installation Xcode einmal öffnen und License akzeptieren
• Developer Directory auf Xcode setzen:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

Prüfen:

xcode-select -p
# Ausgabe: /Applications/Xcode.app/Contents/Developer

3. Capacitor Dependencies installieren

cd ~/Sites/thats-me.local/frontend/src-capacitor
npm install

⚠️ Wichtig: npm install immer nur im src-capacitor/-Unterordner ausführen, niemals direkt im frontend/-Ordner vom Mac-Host. Der frontend/-Ordner ist per Volume in den Docker-Container gemountet. Ein npm install dort überschreibt die Linux-Binaries mit macOS-Binaries und der Dev-Container funktioniert nicht mehr.

Falls das passiert, im Dev-Container reparieren:

cd /workspace/frontend
rm -rf node_modules package-lock.json && npm install

4. iOS-Plattform hinzufügen (nur wenn ios/-Ordner fehlt)

cd ~/Sites/thats-me.local/frontend/src-capacitor
npx cap add ios

5. CocoaPods für iOS-Projekt initialisieren

cd ~/Sites/thats-me.local/frontend/src-capacitor/ios/App
pod install

---

Build & Simulator starten (regulärer Workflow)

Schritt 1 – App bauen

cd ~/Sites/thats-me.local/frontend
npx quasar build -m capacitor -T ios

Das kompiliert den Vue/Quasar-Code und synchronisiert die Assets in das Xcode-Projekt.

Schritt 2 – In Xcode öffnen

cd src-capacitor
npx cap open ios

Schritt 3 – Im Simulator ausführen

In Xcode:

1. Oben links das Zielgerät auf einen Simulator setzen (z.B. "iPhone 17")
2. ▶ Play klicken

Hinweis: Für den Simulator wird kein Apple Developer Account / Signing benötigt. Signing ist nur für echte Geräte und den App Store erforderlich.

---

Nach Code-Änderungen

Wenn Änderungen am Vue/Quasar-Code gemacht wurden, immer wieder:

cd ~/Sites/thats-me.local/frontend
npx quasar build -m capacitor -T ios
cd src-capacitor && npx cap open ios

In Xcode dann erneut auf ▶ klicken.

---

Production Build (App Store)

iOS (App Store / TestFlight)

npx quasar build -m capacitor -T ios
cd src-capacitor && npx cap open ios

In Xcode:

• Signing & Capabilities → Apple Developer Account eintragen (kostenpflichtig, $99/Jahr)
• Zielgerät auf "Any iOS Device (arm64)" setzen
• Product → Archive → Distribute App

Android (Google Play)

npx quasar build -m capacitor -T android
cd src-capacitor && npx cap open android

In Android Studio:

• Build → Generate Signed Bundle / APK
• Keystore erstellen/auswählen

---

Native APIs / Plugins

Capacitor-Plugins ermöglichen Zugriff auf native Funktionen:

# Beispiele (im src-capacitor Ordner):
npm install @capacitor/camera
npm install @capacitor/geolocation
npm install @capacitor/push-notifications

# Nach jedem neuen Plugin:
npx cap sync

---

Git-Hinweise

Folgende Ordner sind in .gitignore und werden nicht commitet:

src-capacitor/node_modules/   # Lokal neu installieren mit: npm install
src-capacitor/www/            # Wird vom Build befüllt
src-capacitor/ios/            # Lokal generiert mit: npx cap add ios
src-capacitor/android/        # Lokal generiert mit: npx cap add android

Was commitet wird:

• src-capacitor/capacitor.config.json – App-Konfiguration
• src-capacitor/package.json – Capacitor Dependencies

---

Troubleshooting

Fehler	Lösung
spawn pod ENOENT	brew install cocoapods
xcodebuild requires Xcode	sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
Cannot find module @rollup/rollup-darwin-arm64	rm -rf node_modules package-lock.json && npm install im frontend/-Ordner
Signing requires a development team	Für Simulator: ignorieren. Für echtes Gerät: Apple Developer Account in Xcode hinterlegen
ios platform already exists	Normal – npx cap add ios überspringen, Ordner ist bereits vorhanden
Weißer Bildschirm im Simulator	npx cap sync im src-capacitor-Ordner, dann neu bauen
Pod-Fehler	cd src-capacitor/ios/App && pod install --repo-update