trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

docs(build): comprehensive BUILDING.md updates for test apps and deployment

Browse Source 
- Add detailed documentation for Vue 3 test app (test-apps/daily-notification-test/)
- Add comprehensive /android/app structure and editing guidelines
- Document all 15+ build scripts in scripts/ directory
- Add deployment section covering npm publishing and external project integration
- Clarify distinction between plugin module and test app modules
- Update Android Studio capabilities (can now run test apps, test notifications)
- Add complete project structure including test apps and scripts
- Document build processes for all three Android components (plugin, main app, Vue app)

Covers full development workflow from plugin development to production deployment.
Co-authored-by: Matthew Raymer
This commit is contained in:
Matthew Raymer
2025-10-21 09:30:22 +00:00
parent 0287764a23
commit fda0124aa5
1 changed files with 372 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

408
BUILDING.md
View File

@@ -1,7 +1,7 @@
# Building the DailyNotification Plugin
**Author**: Matthew Raymer
**Last Updated**: 2025-10-12 04:57:00 UTC
**Last Updated**: 2025-10-21 09:03:53 UTC
**Version**: 1.0.0
## Overview
@@ -201,17 +201,18 @@ When opened correctly, you'll see:
```
android/
├── app/ # Test app (may not be fully configured)
│ ├── build.gradle
│ ├── src/main/
│ └── ...
├── app/ # Main Android test app
│ ├── build.gradle # App build configuration
│ ├── src/main/java/ # MainActivity.java
│ ├── src/main/assets/ # Capacitor assets (HTML/JS)
│ └── build/outputs/apk/ # Built APK files
├── plugin/ # Plugin library module
│ ├── build.gradle
│ ├── build.gradle # Plugin build configuration
│ ├── src/main/java/
│ │ └── com/timesafari/dailynotification/
│ │ ├── DailyNotificationPlugin.kt
│ │ ├── FetchWorker.kt
│ │ ├── NotifyReceiver.kt
│ │ ├── DailyNotificationPlugin.java
│ │ ├── DailyNotificationWorker.java
│ │ ├── DailyNotificationScheduler.java
│ │ └── ...
│ └── build/outputs/aar/
│ └── plugin-release.aar # Built plugin AAR
@@ -221,29 +222,39 @@ android/
└── gradle/wrapper/ # Gradle wrapper files
```
### Important Limitations
**Note**: There's also a separate Vue 3 test app at `test-apps/daily-notification-test/android/` with its own Android module.
#### This is NOT a Full Android App
- **No MainActivity** - This is a plugin, not an app
### Important Distinctions
#### Plugin Module (`android/plugin/`)
- **Purpose**: Contains the actual plugin code
- **No MainActivity** - This is a library, not an app
- **No UI Components** - Plugins provide functionality to host apps
- **No App Manifest** - The host app provides the manifest
- **No Resources** - Plugins use host app resources
- **Output**: AAR library files
#### Test App Module (`android/app/`)
- **Purpose**: Test application for the plugin
- **Has MainActivity** - Full Capacitor app with BridgeActivity
- **Has UI Components** - HTML/JS interface for testing
- **Output**: APK files for installation
#### What You CAN Do in Android Studio
✅ **Edit Kotlin/Java code**
✅ **Run unit tests**
✅ **Debug plugin code**
✅ **Build the plugin AAR**
✅ **Edit Java/Kotlin code** (both plugin and app)
✅ **Run unit tests** (both modules)
✅ **Debug plugin code** (plugin module)
✅ **Build the plugin AAR** (plugin module)
✅ **Build test app APK** (app module)
✅ **Run the test app** (app module)
✅ **Test notifications** (app module)
✅ **Test background tasks** (app module)
✅ **Debug full integration** (app module)
✅ **Check for compilation errors**
✅ **Use code completion and refactoring**
✅ **View build logs and errors**
#### What You CANNOT Do
❌ **Run the app directly** (no MainActivity)
❌ **Test notifications** (needs host app context)
❌ **Test background tasks** (needs Capacitor runtime)
❌ **Debug full integration** (needs host app)
❌ **Test UI components** (plugin has no UI)
❌ **Run plugin module directly** (it's a library)
❌ **Test plugin without host app** (needs Capacitor runtime)
## Command Line Building
@@ -355,9 +366,180 @@ xcodebuild test -workspace DailyNotificationPlugin.xcworkspace \
-destination 'platform=iOS Simulator,name=iPhone 14'
```
### Test Apps Within Project
#### Vue 3 Test Application
The project includes a comprehensive Vue 3 test app for interactive plugin testing:
```bash
# Navigate to Vue 3 test app
cd test-apps/daily-notification-test
# Install dependencies
npm install
# Build Vue 3 app
npm run build
# Sync with Capacitor
npx cap sync android
# Run on Android device/emulator
npx cap run android
# Run on iOS device/simulator
npx cap run ios
```
**Test App Features:**
- Interactive plugin testing interface
- Plugin diagnostics and status checking
- Notification scheduling and management
- Permission testing and management
- Comprehensive logging and debugging
**Test App Structure:**
```
test-apps/daily-notification-test/
├── src/ # Vue 3 source code
│ ├── views/ # Test interface views
│ ├── components/ # Reusable UI components
│ └── stores/ # Pinia state management
├── android/ # Android Capacitor app
├── docs/ # Test app documentation
└── scripts/ # Test app build scripts
```
#### Android Test Apps
The project includes **two separate Android test applications**:
##### 1. Main Android Test App (`/android/app`)
A Capacitor-based Android test app with full plugin integration:
```bash
# Build main Android test app
cd android
./gradlew :app:assembleDebug
# Install on device
adb install app/build/outputs/apk/debug/app-debug.apk
# Run tests
./gradlew :app:test
# Run in Android Studio
# File → Open → /path/to/daily-notification-plugin/android
# Select 'app' module and run
```
**App Structure:**
```
android/app/
├── src/
│ ├── main/
│ │ ├── AndroidManifest.xml # App manifest with permissions
│ │ ├── assets/ # Capacitor web assets
│ │ │ ├── capacitor.config.json # Capacitor configuration
│ │ │ ├── capacitor.plugins.json # Plugin registry
│ │ │ └── public/ # Web app files
│ │ │ ├── index.html # Main test interface
│ │ │ ├── cordova.js # Cordova compatibility
│ │ │ └── plugins/ # Plugin JS files
│ │ ├── java/
│ │ │ └── com/timesafari/dailynotification/
│ │ │ └── MainActivity.java # Capacitor BridgeActivity
│ │ └── res/ # Android resources
│ │ ├── drawable/ # App icons and images
│ │ ├── layout/ # Android layouts
│ │ ├── mipmap/ # App launcher icons
│ │ ├── values/ # Strings, styles, colors
│ │ └── xml/ # Configuration files
│ ├── androidTest/ # Instrumented tests
│ └── test/ # Unit tests
├── build.gradle # App build configuration
├── capacitor.build.gradle # Auto-generated Capacitor config
└── proguard-rules.pro # Code obfuscation rules
```
**Key Files Explained:**
**`MainActivity.java`** - Entry point extending Capacitor's BridgeActivity:
```java
public class MainActivity extends BridgeActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
}
}
```
**`AndroidManifest.xml`** - App permissions and configuration:
- Notification permissions
- Background execution permissions
- Exact alarm permissions
- Capacitor plugin declarations
**`assets/public/index.html`** - Main test interface:
- Interactive plugin testing buttons
- Plugin diagnostics and status checking
- Notification scheduling interface
- Permission management UI
**`capacitor.plugins.json`** - Plugin registry:
```json
{
"plugins": {
"DailyNotification": {
"class": "com.timesafari.dailynotification.DailyNotificationPlugin"
}
}
}
```
**Build Process:**
1. **Web Assets**: Capacitor copies `assets/public/` to APK
2. **Java Compilation**: Compiles `MainActivity.java` and dependencies
3. **Resource Processing**: Processes Android resources and assets
4. **APK Generation**: Packages everything into installable APK
5. **Plugin Integration**: Links with plugin AAR from `android/plugin/`
**Editing Guidelines:**
- **HTML/JS**: Edit `assets/public/index.html` for UI changes
- **Java**: Edit `src/main/java/` for native Android code
- **Resources**: Edit `src/main/res/` for icons, strings, layouts
- **Configuration**: Edit `AndroidManifest.xml` for permissions
- **Build**: Modify `build.gradle` for dependencies and build settings
**Features:**
- Full Capacitor integration
- Plugin testing interface (HTML/JS)
- Native Android testing capabilities
- Complete app lifecycle testing
##### 2. Vue 3 Test App Android Module (`/test-apps/daily-notification-test/android`)
Android module within the Vue 3 test application:
```bash
# Build Vue 3 test app Android module
cd test-apps/daily-notification-test/android
./gradlew assembleDebug
# Install on device
adb install app/build/outputs/apk/debug/app-debug.apk
# Run tests
./gradlew test
```
**Features:**
- Integrated with Vue 3 frontend
- Plugin diagnostics and management
- Interactive testing interface
- Comprehensive logging and debugging
### Integration Testing
#### 1. Create Test Capacitor App
#### 1. Create External Test Capacitor App
```bash
# Create new Capacitor app
npx @capacitor/create-app@latest TestApp
@@ -419,7 +601,124 @@ npx cap run ios
- [ ] Battery optimization settings
- [ ] Low storage conditions
## Development Workflow
## Build Scripts and Automation
### Available Build Scripts
The project includes several automated build scripts in the `scripts/` directory:
#### Core Build Scripts
```bash
# Main build script (handles TypeScript + native)
./scripts/build-native.sh --platform android
./scripts/build-native.sh --platform ios
./scripts/build-native.sh --verbose
# TimeSafari-specific builds
node scripts/build-timesafari.js
# Comprehensive testing
./scripts/comprehensive-test-v2.sh
# Capacitor build fixes
./scripts/fix-capacitor-build.sh
```
#### Setup and Configuration Scripts
```bash
# Gradle setup automation
./scripts/setup-gradle.sh
# Native environment setup
node scripts/setup-native.js
# Environment checking
node scripts/check-environment.js
```
#### Testing and Validation Scripts
```bash
# Chaos testing for reliability
node scripts/chaos-test.js
# API changes detection
node scripts/check-api-changes.js
# Bundle size monitoring
node scripts/check-bundle-size.js
# Daily notification testing
./scripts/daily-notification-test.sh
node scripts/daily-notification-test.py
```
#### Release and Deployment Scripts
```bash
# Release notes generation
node scripts/update-release-notes.js
# Type checksum generation
node scripts/generate-types-checksum.js
```
### Deployment to External Projects
#### 1. Publishing to npm Registry
```bash
# Build the plugin
npm run build
# Run tests
npm test
# Update version
npm version patch # or minor, major
# Publish to npm
npm publish
# Verify publication
npm view @timesafari/daily-notification-plugin
```
#### 2. Installing in External Capacitor Projects
```bash
# Install from npm
npm install @timesafari/daily-notification-plugin
# Install from local development
npm install /path/to/daily-notification-plugin
# Install from git repository
npm install git+https://github.com/timesafari/daily-notification-plugin.git
```
#### 3. Integration in Host Applications
```bash
# Add to Capacitor project
npx cap add android
npx cap add ios
# Sync with Capacitor
npx cap sync android
npx cap sync ios
# Build and run
npx cap run android
npx cap run ios
```
#### 4. Version Management
```bash
# Check current version
npm list @timesafari/daily-notification-plugin
# Update to latest version
npm update @timesafari/daily-notification-plugin
# Install specific version
npm install @timesafari/daily-notification-plugin@1.2.3
```
### For Plugin Development
@@ -612,7 +911,9 @@ daily-notification-plugin/
├── ios/ # iOS native code
├── src/ # TypeScript plugin interface
├── dist/ # Built plugin files
├── scripts/ # Build scripts
├── scripts/ # Build scripts and automation
├── test-apps/ # Test applications
│ └── daily-notification-test/ # Vue 3 test app
├── docs/ # Documentation
├── examples/ # Usage examples
├── tests/ # Test files
@@ -625,8 +926,16 @@ daily-notification-plugin/
### Android Structure
```
android/
├── src/main/java/ # Kotlin plugin code
├── build.gradle # Android build configuration
├── app/ # Main Android test app
│ ├── src/main/java/ # MainActivity.java
│ ├── src/main/assets/ # Capacitor assets
│ ├── build.gradle # App build configuration
│ └── build/outputs/apk/ # Built APK files
├── plugin/ # Plugin library module
│ ├── src/main/java/ # Plugin source code
│ ├── build.gradle # Plugin build configuration
│ └── build/outputs/aar/ # Built AAR files
├── build.gradle # Root Android build configuration
├── settings.gradle # Gradle settings
├── gradle.properties # Gradle properties
└── gradle/wrapper/ # Gradle wrapper files
@@ -642,15 +951,42 @@ ios/
└── Tests/ # iOS unit tests
```
### TypeScript Structure
### Test Apps Structure
```
src/
├── definitions.ts # TypeScript definitions
├── index.ts # Plugin entry point
├── android/ # Android-specific code
├── ios/ # iOS-specific code
├── web/ # Web-specific code (legacy)
└── utils/ # Utility functions
test-apps/
└── daily-notification-test/ # Vue 3 test application
├── src/ # Vue 3 source code
│ ├── views/ # Test interface views
│ ├── components/ # Reusable UI components
│ ├── stores/ # Pinia state management
│ └── router/ # Vue Router configuration
├── android/ # Android Capacitor app
│ ├── app/ # Android app module
│ ├── dailynotification/ # Plugin module
│ └── build.gradle # Android build config
├── docs/ # Test app documentation
├── scripts/ # Test app build scripts
├── package.json # Vue 3 dependencies
└── vite.config.ts # Vite build configuration
```
### Scripts Structure
```
scripts/
├── build-native.sh # Main build script
├── build-timesafari.js # TimeSafari-specific builds
├── comprehensive-test-v2.sh # Full test suite
├── fix-capacitor-build.sh # Capacitor build fixes
├── setup-gradle.sh # Gradle setup automation
├── setup-native.js # Native environment setup
├── check-environment.js # Environment validation
├── chaos-test.js # Reliability testing
├── check-api-changes.js # API change detection
├── check-bundle-size.js # Bundle size monitoring
├── daily-notification-test.sh # Notification testing
├── daily-notification-test.py # Python test runner
├── update-release-notes.js # Release notes generation
└── generate-types-checksum.js # Type checksum generation
```
## Best Practices