d8a0eaf413
- Android: move plugin source to org/timesafari/dailynotification, update namespace, manifest package, and all package/imports; change intent actions to org.timesafari.daily.NOTIFICATION and DISMISS - iOS: update bundle IDs, BGTask identifiers, subsystem labels, and queue names in Plugin and Xcode projects - Capacitor: update plugin class registration and appIds in configs - Test apps (android-test-app, daily-notification-test, ios-test-app): applicationId/bundleId, manifests, ProGuard, scripts, and docs - Docs: bulk update references; add CONSUMING_APP_MIGRATION_COM_TO_ORG.md for consuming app migration BREAKING CHANGE: Consuming apps must update plugin class to org.timesafari.dailynotification.DailyNotificationPlugin, manifest receivers/actions, and iOS BGTask identifiers per migration doc.
334 lines
8.6 KiB
Markdown
334 lines
8.6 KiB
Markdown
# Build Process Quick Reference
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: October 17, 2025
|
|
**Last Updated**: November 19, 2025
|
|
|
|
## ⚡ Quick Start
|
|
|
|
**Easiest way to build and run:**
|
|
|
|
```bash
|
|
# Build and run both platforms
|
|
./scripts/build.sh --run
|
|
|
|
# Or build only
|
|
./scripts/build.sh
|
|
```
|
|
|
|
This script handles everything automatically! See [Unified Build Script](#-unified-build-script-recommended) section for all options.
|
|
|
|
---
|
|
|
|
## 🚨 Critical Build Steps
|
|
|
|
### Prerequisites
|
|
|
|
**Required for All Platforms:**
|
|
- Node.js 20.19.0+ or 22.12.0+
|
|
- npm (comes with Node.js)
|
|
- Plugin must be built (`npm run build` in plugin root directory)
|
|
- The build script will automatically build the plugin if `dist/` doesn't exist
|
|
|
|
**For Android:**
|
|
- Java JDK 22.12 or later
|
|
- Android SDK (with `adb` in PATH)
|
|
- Gradle (comes with Android project)
|
|
|
|
**For iOS:**
|
|
- macOS with Xcode (xcodebuild must be in PATH)
|
|
- CocoaPods (`pod --version` to check)
|
|
- Can be installed via rbenv (script handles this automatically)
|
|
- iOS deployment target: iOS 13.0+
|
|
|
|
**Plugin Requirements:**
|
|
- Plugin podspec must exist at: `node_modules/@timesafari/daily-notification-plugin/ios/DailyNotificationPlugin.podspec`
|
|
- Plugin must be installed: `npm install` (uses `file:../../` reference)
|
|
- Plugin must be built: `npm run build` in plugin root (creates `dist/` directory)
|
|
|
|
### Initial Setup (One-Time)
|
|
|
|
```bash
|
|
# 1. Install dependencies (includes @capacitor/ios)
|
|
npm install
|
|
|
|
# 2. Add iOS platform (if not already added)
|
|
npx cap add ios
|
|
|
|
# 3. Install iOS dependencies
|
|
cd ios/App
|
|
pod install
|
|
cd ../..
|
|
```
|
|
|
|
### Build for Both Platforms
|
|
|
|
```bash
|
|
# 1. Build web assets (required for both platforms)
|
|
npm run build
|
|
|
|
# 2. Sync with native projects (syncs both Android and iOS)
|
|
npm run cap:sync
|
|
|
|
# OR sync platforms individually:
|
|
# npm run cap:sync:android # Android only
|
|
# npm run cap:sync:ios # iOS only
|
|
```
|
|
|
|
### Android Build
|
|
|
|
```bash
|
|
# Build Android APK
|
|
cd android
|
|
./gradlew :app:assembleDebug
|
|
|
|
# Install on device/emulator
|
|
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
|
|
|
# Launch app
|
|
adb shell am start -n org.timesafari.dailynotification.test/.MainActivity
|
|
```
|
|
|
|
### iOS Build
|
|
|
|
```bash
|
|
# Open in Xcode
|
|
cd ios/App
|
|
open App.xcworkspace
|
|
|
|
# Or build from command line
|
|
xcodebuild -workspace App.xcworkspace \
|
|
-scheme App \
|
|
-configuration Debug \
|
|
-sdk iphonesimulator \
|
|
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
|
build
|
|
|
|
# Or use Capacitor CLI
|
|
npx cap run ios
|
|
```
|
|
|
|
## ⚠️ Why `npm run cap:sync` is Important
|
|
|
|
**Problem**: `npx cap sync` overwrites `capacitor.plugins.json` and `capacitor.settings.gradle` with incorrect paths.
|
|
|
|
**Solution**: The `cap:sync` script automatically:
|
|
1. Runs `npx cap sync` (syncs both Android and iOS)
|
|
2. Fixes `capacitor.settings.gradle` (corrects plugin path from `android/` to `android/plugin/`)
|
|
3. Restores the DailyNotification plugin entry in `capacitor.plugins.json`
|
|
|
|
**Platform-specific sync:**
|
|
- `npm run cap:sync:android` - Syncs Android only (includes fix script)
|
|
- `npm run cap:sync:ios` - Syncs iOS only (no fix needed for iOS)
|
|
|
|
**Without the fix**: Plugin detection fails, build errors occur, "simplified dialog" appears.
|
|
|
|
## 🔍 Verification Checklist
|
|
|
|
### Android Verification
|
|
|
|
After Android build, verify:
|
|
|
|
- [ ] `android/app/src/main/assets/capacitor.plugins.json` contains DailyNotification entry
|
|
- [ ] System Status shows "Plugin: Available" (green)
|
|
- [ ] Plugin Diagnostics shows all 4 plugins
|
|
- [ ] Click events work on ActionCard components
|
|
- [ ] No "simplified dialog" appears
|
|
|
|
### iOS Verification
|
|
|
|
After iOS build, verify:
|
|
|
|
- [ ] iOS project exists at `ios/App/App.xcworkspace`
|
|
- [ ] CocoaPods installed (`pod install` completed successfully)
|
|
- [ ] Plugin framework linked in Xcode project
|
|
- [ ] App builds without errors in Xcode
|
|
- [ ] Plugin methods accessible from JavaScript
|
|
- [ ] System Status shows "Plugin: Available" (green)
|
|
|
|
## 🛠️ Automated Build Scripts
|
|
|
|
### Unified Build Script (Recommended)
|
|
|
|
The project includes a comprehensive build script that handles both platforms:
|
|
|
|
```bash
|
|
# Build both platforms
|
|
./scripts/build.sh
|
|
|
|
# Build Android only
|
|
./scripts/build.sh --android
|
|
|
|
# Build iOS only
|
|
./scripts/build.sh --ios
|
|
|
|
# Build and run Android on emulator
|
|
./scripts/build.sh --run-android
|
|
|
|
# Build and run iOS on simulator
|
|
./scripts/build.sh --run-ios
|
|
|
|
# Build and run both platforms
|
|
./scripts/build.sh --run
|
|
|
|
# Show help
|
|
./scripts/build.sh --help
|
|
```
|
|
|
|
**Features:**
|
|
- ✅ Automatically builds web assets
|
|
- ✅ Syncs Capacitor with both platforms
|
|
- ✅ Builds Android APK
|
|
- ✅ Builds iOS app for simulator
|
|
- ✅ Automatically finds and uses available emulator/simulator
|
|
- ✅ Installs and launches apps when using `--run` flags
|
|
- ✅ Color-coded output for easy reading
|
|
- ✅ Comprehensive error handling
|
|
|
|
### Manual Build Scripts
|
|
|
|
#### Build for Android
|
|
|
|
Create `scripts/build-android.sh`:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
set -e
|
|
|
|
echo "🔨 Building web assets..."
|
|
npm run build
|
|
|
|
echo "🔄 Syncing with native projects..."
|
|
npm run cap:sync:android
|
|
# This automatically syncs and fixes plugin paths
|
|
|
|
echo "🏗️ Building Android app..."
|
|
cd android
|
|
./gradlew :app:assembleDebug
|
|
|
|
echo "📱 Installing and launching..."
|
|
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
|
adb shell am start -n org.timesafari.dailynotification.test/.MainActivity
|
|
|
|
echo "✅ Android build and deploy complete!"
|
|
```
|
|
|
|
### Build for iOS
|
|
|
|
Create `scripts/build-ios.sh`:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
set -e
|
|
|
|
echo "🔨 Building web assets..."
|
|
npm run build
|
|
|
|
echo "🔄 Syncing with iOS..."
|
|
npm run cap:sync:ios
|
|
|
|
echo "🍎 Building iOS app..."
|
|
cd ios/App
|
|
pod install
|
|
xcodebuild -workspace App.xcworkspace \
|
|
-scheme App \
|
|
-configuration Debug \
|
|
-sdk iphonesimulator \
|
|
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
|
build
|
|
|
|
echo "✅ iOS build complete!"
|
|
echo "📱 Open Xcode to run on simulator: open App.xcworkspace"
|
|
```
|
|
|
|
### Build for Both Platforms
|
|
|
|
Create `scripts/build-all.sh`:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
set -e
|
|
|
|
echo "🔨 Building web assets..."
|
|
npm run build
|
|
|
|
echo "🔄 Syncing with all native projects..."
|
|
npm run cap:sync
|
|
|
|
echo "🏗️ Building Android..."
|
|
cd android && ./gradlew :app:assembleDebug && cd ..
|
|
|
|
echo "🍎 Building iOS..."
|
|
cd ios/App && pod install && cd ../..
|
|
xcodebuild -workspace ios/App/App.xcworkspace \
|
|
-scheme App \
|
|
-configuration Debug \
|
|
-sdk iphonesimulator \
|
|
-destination 'platform=iOS Simulator,name=iPhone 15' \
|
|
build
|
|
|
|
echo "✅ All platforms built successfully!"
|
|
```
|
|
|
|
## 🐛 Common Issues
|
|
|
|
| Issue | Symptom | Solution |
|
|
|-------|---------|----------|
|
|
| Empty plugin registry | `capacitor.plugins.json` is `[]` | Run `npm run cap:sync` or `node scripts/fix-capacitor-plugins.js` |
|
|
| Plugin not detected | "Plugin: Not Available" (red) | Check plugin registry, rebuild |
|
|
| Click events not working | Buttons don't respond | Check Vue 3 compatibility, router config |
|
|
| Inconsistent status | Different status in different cards | Use consistent detection logic |
|
|
| **No podspec found** | `[!] No podspec found for 'TimesafariDailyNotificationPlugin'` | Run `node scripts/fix-capacitor-plugins.js` to fix Podfile, then `pod install` |
|
|
| **Plugin not built** | Vite build fails: "Failed to resolve entry" | Run `npm run build` in plugin root directory (`../../`) |
|
|
| **CocoaPods not found** | `pod: command not found` | Install CocoaPods: `sudo gem install cocoapods` or via rbenv |
|
|
| **Xcode not found** | `xcodebuild: command not found` | Install Xcode from App Store, run `xcode-select --install` |
|
|
|
|
## 📱 Testing Commands
|
|
|
|
### Android Testing
|
|
|
|
```bash
|
|
# Check plugin registry
|
|
cat android/app/src/main/assets/capacitor.plugins.json
|
|
|
|
# Monitor native logs
|
|
adb logcat | grep -i "dailynotification\|capacitor\|plugin"
|
|
|
|
# Check app installation
|
|
adb shell pm list packages | grep dailynotification
|
|
|
|
# View app logs
|
|
adb logcat -s DailyNotification
|
|
```
|
|
|
|
### iOS Testing
|
|
|
|
```bash
|
|
# Check if iOS project exists
|
|
ls -la ios/App/App.xcworkspace
|
|
|
|
# Check CocoaPods installation
|
|
cd ios/App && pod install && cd ../..
|
|
|
|
# Monitor iOS logs (simulator)
|
|
xcrun simctl spawn booted log stream | grep -i "dailynotification\|capacitor\|plugin"
|
|
|
|
# Check plugin in Xcode
|
|
# Open ios/App/App.xcworkspace in Xcode
|
|
# Check: Project Navigator → Frameworks → DailyNotificationPlugin.framework
|
|
|
|
# View device logs (physical device)
|
|
# Xcode → Window → Devices and Simulators → Select device → Open Console
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Important Notes
|
|
|
|
**Remember**:
|
|
- Use `npm run cap:sync` to sync both platforms (automatically fixes Android configuration files)
|
|
- Use `npm run cap:sync:android` for Android-only sync (includes fix script)
|
|
- Use `npm run cap:sync:ios` for iOS-only sync
|
|
- Always run `npm run build` before syncing to ensure latest web assets are copied
|
|
- For iOS: Run `pod install` in `ios/App/` after first sync or when dependencies change
|