docs(test-app): add comprehensive plugin detection and build documentation
- Add PLUGIN_DETECTION_GUIDE.md with complete troubleshooting guide - Add BUILD_QUICK_REFERENCE.md for streamlined build process - Document critical fix-capacitor-plugins.js requirement after npx cap sync - Include verification checklists and common issue solutions - Provide automated build script and debugging tools - Cover Vue 3 compatibility issues and click event troubleshooting These docs ensure reliable plugin detection and prevent the common issue where npx cap sync overwrites capacitor.plugins.json.
This commit is contained in:
Matthew Raymer
@@ -0,0 +1,95 @@
|
||||
# Build Process Quick Reference
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: October 17, 2025
|
||||
|
||||
## 🚨 Critical Build Steps
|
||||
|
||||
```bash
|
||||
# 1. Build web assets
|
||||
npm run build
|
||||
|
||||
# 2. Sync with native projects
|
||||
npx cap sync android
|
||||
|
||||
# 3. 🔧 FIX PLUGIN REGISTRY (REQUIRED!)
|
||||
node scripts/fix-capacitor-plugins.js
|
||||
|
||||
# 4. Build and deploy Android
|
||||
cd android
|
||||
./gradlew :app:assembleDebug
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity
|
||||
```
|
||||
|
||||
## ⚠️ Why Step 3 is Critical
|
||||
|
||||
**Problem**: `npx cap sync` overwrites `capacitor.plugins.json` and removes custom plugins.
|
||||
|
||||
**Solution**: The fix script restores the DailyNotification plugin entry.
|
||||
|
||||
**Without Step 3**: Plugin detection fails, "simplified dialog" appears.
|
||||
|
||||
## 🔍 Verification Checklist
|
||||
|
||||
After build, verify:
|
||||
|
||||
- [ ] `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
|
||||
|
||||
## 🛠️ Automated Build Script
|
||||
|
||||
Create `scripts/build-and-deploy.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🔨 Building web assets..."
|
||||
npm run build
|
||||
|
||||
echo "🔄 Syncing with native projects..."
|
||||
npx cap sync android
|
||||
|
||||
echo "🔧 Fixing plugin registry..."
|
||||
node scripts/fix-capacitor-plugins.js
|
||||
|
||||
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 "✅ Build and deploy complete!"
|
||||
```
|
||||
|
||||
## 🐛 Common Issues
|
||||
|
||||
| Issue | Symptom | Solution |
|
||||
|-------|---------|----------|
|
||||
| Empty plugin registry | `capacitor.plugins.json` is `[]` | Run `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 |
|
||||
|
||||
## 📱 Testing Commands
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Always run the fix script after `npx cap sync`!
|
||||
324
test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md
Normal file
324
test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# DailyNotification Plugin Detection Guide
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: October 17, 2025
|
||||
**Version**: 1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
This guide documents the plugin detection system for the DailyNotification Capacitor plugin, including troubleshooting steps and build process requirements.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Plugin Detection Architecture](#plugin-detection-architecture)
|
||||
2. [Build Process Requirements](#build-process-requirements)
|
||||
3. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
4. [Development Workflow](#development-workflow)
|
||||
5. [Common Issues and Solutions](#common-issues-and-solutions)
|
||||
|
||||
## Plugin Detection Architecture
|
||||
|
||||
### Native Side (Android)
|
||||
|
||||
The DailyNotification plugin is registered on the native Android side through:
|
||||
|
||||
1. **Automatic Discovery**: Using Capacitor's annotation processor
|
||||
2. **Manual Registration**: Fallback in `MainActivity.onCreate()`
|
||||
3. **Plugin Class**: `com.timesafari.dailynotification.DailyNotificationPlugin`
|
||||
|
||||
### JavaScript Side (WebView)
|
||||
|
||||
The JavaScript layer detects plugins through:
|
||||
|
||||
1. **`capacitor.plugins.json`**: Bridge file that lists available plugins
|
||||
2. **Capacitor.Plugins Object**: Runtime plugin registry
|
||||
3. **Plugin Detection Logic**: Checks both sources for availability
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
android/
|
||||
├── app/src/main/assets/capacitor.plugins.json # Plugin registry
|
||||
├── app/src/main/java/.../MainActivity.java # Plugin registration
|
||||
└── dailynotification/build.gradle # Annotation processor
|
||||
|
||||
src/
|
||||
├── views/HomeView.vue # Plugin detection UI
|
||||
└── components/cards/ActionCard.vue # Interactive components
|
||||
```
|
||||
|
||||
## Build Process Requirements
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Annotation Processor**: Must be configured in both app and plugin modules
|
||||
2. **Post-Sync Script**: Required to maintain `capacitor.plugins.json`
|
||||
3. **Proper Dependencies**: Capacitor Android and plugin modules
|
||||
|
||||
### Required Build Steps
|
||||
|
||||
```bash
|
||||
# 1. Build web assets
|
||||
npm run build
|
||||
|
||||
# 2. Sync with native projects
|
||||
npx cap sync android
|
||||
|
||||
# 3. Fix plugin registry (CRITICAL)
|
||||
node scripts/fix-capacitor-plugins.js
|
||||
|
||||
# 4. Build and deploy Android app
|
||||
cd android
|
||||
./gradlew :app:assembleDebug
|
||||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||||
adb shell am start -n com.timesafari.dailynotification.test/.MainActivity
|
||||
```
|
||||
|
||||
### Why the Fix Script is Required
|
||||
|
||||
**Problem**: `npx cap sync android` overwrites `capacitor.plugins.json` and doesn't include custom plugins.
|
||||
|
||||
**Solution**: Post-sync script automatically restores the DailyNotification plugin entry.
|
||||
|
||||
**File**: `scripts/fix-capacitor-plugins.js`
|
||||
|
||||
```javascript
|
||||
const PLUGIN_ENTRY = {
|
||||
name: "DailyNotification",
|
||||
classpath: "com.timesafari.dailynotification.DailyNotificationPlugin"
|
||||
};
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Issue: "Plugin: Not Available" in System Status
|
||||
|
||||
**Symptoms**:
|
||||
- System Status card shows red "Not Available" indicator
|
||||
- Plugin Diagnostics shows "Plugin Available: No"
|
||||
|
||||
**Diagnosis Steps**:
|
||||
1. Check `capacitor.plugins.json` content
|
||||
2. Verify native plugin registration logs
|
||||
3. Test JavaScript detection logic
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check plugin registry
|
||||
cat android/app/src/main/assets/capacitor.plugins.json
|
||||
|
||||
# Should contain:
|
||||
[
|
||||
{
|
||||
"name": "DailyNotification",
|
||||
"classpath": "com.timesafari.dailynotification.DailyNotificationPlugin"
|
||||
}
|
||||
]
|
||||
|
||||
# If empty or missing, run fix script
|
||||
node scripts/fix-capacitor-plugins.js
|
||||
```
|
||||
|
||||
### Issue: Click Events Not Working
|
||||
|
||||
**Symptoms**:
|
||||
- ActionCard buttons don't respond to clicks
|
||||
- No console logs from click handlers
|
||||
|
||||
**Common Causes**:
|
||||
1. **Wrong View Component**: Router pointing to simplified view
|
||||
2. **Vue 3 Compatibility**: Using deprecated `@click.native`
|
||||
3. **Component Registration**: Missing component imports
|
||||
|
||||
**Solutions**:
|
||||
```vue
|
||||
<!-- ❌ Wrong: Vue 3 doesn't support .native -->
|
||||
<ActionCard @click.native="handler" />
|
||||
|
||||
<!-- ✅ Correct: Standard event binding -->
|
||||
<ActionCard @click="handler" />
|
||||
```
|
||||
|
||||
### Issue: Empty capacitor.plugins.json After Build
|
||||
|
||||
**Symptoms**:
|
||||
- File contains only `[]`
|
||||
- Plugin detection fails
|
||||
- "Simplified dialog" appears
|
||||
|
||||
**Root Cause**: `npx cap sync` overwrites the file
|
||||
|
||||
**Solution**: Always run fix script after sync
|
||||
```bash
|
||||
npx cap sync android && node scripts/fix-capacitor-plugins.js
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily Development Cycle
|
||||
|
||||
1. **Make Changes**: Edit Vue components, native code, or plugin logic
|
||||
2. **Build Web**: `npm run build`
|
||||
3. **Sync Native**: `npx cap sync android`
|
||||
4. **Fix Plugins**: `node scripts/fix-capacitor-plugins.js`
|
||||
5. **Build Android**: `cd android && ./gradlew :app:assembleDebug`
|
||||
6. **Deploy**: `adb install -r app/build/outputs/apk/debug/app-debug.apk`
|
||||
7. **Test**: Launch app and verify plugin detection
|
||||
|
||||
### Automated Build Script
|
||||
|
||||
Create `scripts/build-and-deploy.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🔨 Building web assets..."
|
||||
npm run build
|
||||
|
||||
echo "🔄 Syncing with native projects..."
|
||||
npx cap sync android
|
||||
|
||||
echo "🔧 Fixing plugin registry..."
|
||||
node scripts/fix-capacitor-plugins.js
|
||||
|
||||
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 "✅ Build and deploy complete!"
|
||||
```
|
||||
|
||||
### Verification Checklist
|
||||
|
||||
After each build, verify:
|
||||
|
||||
- [ ] `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
|
||||
- [ ] Console logs show plugin detection success
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: Annotation Processor Not Working
|
||||
|
||||
**Symptoms**: Plugin not auto-discovered, manual registration required
|
||||
|
||||
**Solution**: Ensure annotation processor is configured in both modules
|
||||
|
||||
```gradle
|
||||
// app/build.gradle
|
||||
dependencies {
|
||||
annotationProcessor project(':capacitor-android')
|
||||
}
|
||||
|
||||
// dailynotification/build.gradle
|
||||
dependencies {
|
||||
annotationProcessor project(':capacitor-android')
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: Plugin Loads But Methods Fail
|
||||
|
||||
**Symptoms**: Plugin detected but `checkStatus()` throws errors
|
||||
|
||||
**Diagnosis**: Check native plugin implementation and permissions
|
||||
|
||||
**Solution**: Verify plugin class methods and Android permissions
|
||||
|
||||
### Issue: Inconsistent Status Between Cards
|
||||
|
||||
**Symptoms**: System Status shows "Not Available" but Plugin Diagnostics shows "Available"
|
||||
|
||||
**Root Cause**: Different detection logic between functions
|
||||
|
||||
**Solution**: Use consistent detection method (see `checkSystemStatus` in HomeView.vue)
|
||||
|
||||
### Issue: Build Failures After Changes
|
||||
|
||||
**Symptoms**: Gradle build errors, TypeScript compilation failures
|
||||
|
||||
**Common Causes**:
|
||||
1. Missing imports after refactoring
|
||||
2. TypeScript errors in Vue components
|
||||
3. Gradle dependency conflicts
|
||||
|
||||
**Solution**: Check build logs and fix compilation errors
|
||||
|
||||
## Debugging Tools
|
||||
|
||||
### Console Logging
|
||||
|
||||
The app includes comprehensive logging for plugin detection:
|
||||
|
||||
```javascript
|
||||
// Plugin detection logs
|
||||
console.log('🔍 Plugin detection debug:')
|
||||
console.log(' - window.DailyNotification:', (window as any).DailyNotification)
|
||||
console.log(' - Capacitor.Plugins:', (window as any).Capacitor?.Plugins)
|
||||
console.log(' - Available plugins:', Object.keys((window as any).Capacitor?.Plugins || {}))
|
||||
```
|
||||
|
||||
### ADB Logging
|
||||
|
||||
Monitor native Android logs:
|
||||
|
||||
```bash
|
||||
adb logcat | grep -i "dailynotification\|capacitor\|plugin\|error"
|
||||
```
|
||||
|
||||
### Plugin Diagnostics
|
||||
|
||||
Use the built-in Plugin Diagnostics feature to get comprehensive system information:
|
||||
|
||||
1. Click "Plugin Diagnostics" button
|
||||
2. Review detailed plugin report
|
||||
3. Check all available plugins list
|
||||
4. Verify plugin status and capabilities
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development
|
||||
|
||||
1. **Always run fix script** after `npx cap sync`
|
||||
2. **Test plugin detection** after each build
|
||||
3. **Use consistent detection logic** across components
|
||||
4. **Monitor console logs** for debugging information
|
||||
5. **Verify both native and JavaScript sides** work correctly
|
||||
|
||||
### Maintenance
|
||||
|
||||
1. **Keep fix script updated** if plugin classpath changes
|
||||
2. **Document any new plugin dependencies**
|
||||
3. **Update this guide** when architecture changes
|
||||
4. **Test on multiple devices** and Android versions
|
||||
5. **Monitor Capacitor updates** for breaking changes
|
||||
|
||||
## Related Files
|
||||
|
||||
- `scripts/fix-capacitor-plugins.js` - Post-sync plugin registry fix
|
||||
- `src/views/HomeView.vue` - Main plugin detection UI
|
||||
- `src/components/cards/ActionCard.vue` - Interactive components
|
||||
- `android/app/src/main/assets/capacitor.plugins.json` - Plugin registry
|
||||
- `android/app/src/main/java/.../MainActivity.java` - Native registration
|
||||
|
||||
## Support
|
||||
|
||||
For issues not covered in this guide:
|
||||
|
||||
1. Check Capacitor documentation
|
||||
2. Review Android plugin development guides
|
||||
3. Examine console logs and ADB output
|
||||
4. Test with minimal reproduction case
|
||||
5. Consult development team
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: October 17, 2025
|
||||
**Next Review**: After major Capacitor updates or architecture changes
|
||||
Reference in New Issue
Block a user