daily-notification-plugin/test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md

Build Process Quick Reference

Author: Matthew Raymer
Date: October 17, 2025
Last Updated: November 19, 2025

⚡ Quick Start

Easiest way to build and run:

# Build and run both platforms
./scripts/build.sh --run

# Or build only
./scripts/build.sh

This script handles everything automatically! See Unified Build Script 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)

# 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

# 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

# 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 com.timesafari.dailynotification.test/.MainActivity

iOS Build

# 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:

# 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:

#!/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 com.timesafari.dailynotification.test/.MainActivity

echo "✅ Android build and deploy complete!"

Build for iOS

Create scripts/build-ios.sh:

#!/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:

#!/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

# 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

# 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