Browse Source
- 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.master
Matthew Raymer
5 days ago
2 changed files with 419 additions and 0 deletions
@ -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`! |
||||
@ -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 |
||||
Loading…
Reference in new issue