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
4 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