crowd-funder-for-time-pwa/docs/android-build-scripts.md

Android Build Scripts Documentation

Author: Matthew Raymer Date: 2025-07-11 Status: ✅ COMPLETE - Full Android build system integration

Overview

The Android build system for TimeSafari has been integrated with the Vite mode-based pattern, providing consistent environment management and flexible build options across development, testing, and production environments.

Note: All Android builds should be invoked via npm run build:android* scripts for consistency. The legacy build:capacitor:android* scripts are now aliases for the corresponding build:android* scripts.

Build Script Integration

Package.json Scripts

The Android build system is fully integrated into package.json with the following scripts:

Basic Build Commands

# Development builds (defaults to --mode development)
npm run build:android:dev      # Development build
npm run build:android:test     # Testing build
npm run build:android:prod     # Production build

Build Type Commands

# Debug builds
npm run build:android:debug    # Debug APK build

# Release builds
npm run build:android:release  # Release APK build

Specialized Commands

# Android Studio integration
npm run build:android:studio   # Build + open Android Studio

# Package builds
npm run build:android:apk      # Build APK file
npm run build:android:aab      # Build AAB (Android App Bundle)

# Utility commands
npm run build:android:clean    # Clean build artifacts only
npm run build:android:sync     # Sync Capacitor only
npm run build:android:assets   # Generate assets only

Legacy Command

# Original script (maintains backward compatibility)
npm run build:android          # Full build process

Script Usage

Direct Script Usage

The build-android.sh script supports comprehensive command-line options:

# Basic usage
./scripts/build-android.sh [options]

# Environment-specific builds
./scripts/build-android.sh --dev --studio    # Development + open studio
./scripts/build-android.sh --test --apk      # Testing APK build
./scripts/build-android.sh --prod --aab      # Production AAB build

# Utility operations
./scripts/build-android.sh --clean           # Clean only
./scripts/build-android.sh --sync            # Sync only
./scripts/build-android.sh --assets          # Assets only

Command-Line Options

Option	Description	Default
--dev, --development	Build for development environment	✅
--test	Build for testing environment
--prod, --production	Build for production environment
--debug	Build debug APK	✅
--release	Build release APK
--studio	Open Android Studio after build
--apk	Build APK file
--aab	Build AAB (Android App Bundle)
--clean	Clean build artifacts only
--sync	Sync Capacitor only
--assets	Generate assets only
-h, --help	Show help message
-v, --verbose	Enable verbose logging

Build Process

Complete Build Flow

1. Resource Check: Validate Android resources
2. Cleanup: Clean Android app and build artifacts
3. Capacitor Build: Build web assets with environment-specific mode
4. Gradle Clean: Clean Gradle build cache
5. Gradle Build: Assemble debug/release APK
6. Capacitor Sync: Sync web assets to Android platform
7. Asset Generation: Generate Android-specific assets
8. Package Build: Build APK/AAB if requested
9. Studio Launch: Open Android Studio if requested

Environment-Specific Builds

Development Environment (--dev)

# Uses --mode development
npm run build:capacitor
# Builds with development optimizations and debugging enabled

Testing Environment (--test)

# Uses --mode test
npm run build:capacitor -- --mode test
# Builds with testing configurations and test API endpoints

Production Environment (--prod)

# Uses --mode production
npm run build:capacitor -- --mode production
# Builds with production optimizations and live API endpoints

Build Artifacts

APK Files

• Debug APK: android/app/build/outputs/apk/debug/app-debug.apk
• Release APK: android/app/build/outputs/apk/release/app-release.apk

AAB Files

• Release AAB: android/app/build/outputs/bundle/release/app-release.aab

Build Locations

# APK files
android/app/build/outputs/apk/debug/
android/app/build/outputs/apk/release/

# AAB files
android/app/build/outputs/bundle/release/

# Gradle build cache
android/app/build/
android/.gradle/

Environment Variables

The build system automatically sets environment variables based on the build type:

Capacitor Environment

VITE_PLATFORM=capacitor
VITE_PWA_ENABLED=false
VITE_DISABLE_PWA=true
DEBUG_MIGRATIONS=0

Git Integration

VITE_GIT_HASH=<git-commit-hash>
# Automatically set from current git commit

Error Handling

Exit Codes

Code	Description
1	Android cleanup failed
2	Web build failed
3	Capacitor build failed
4	Gradle clean failed
5	Gradle assemble failed
6	Capacitor sync failed
7	Asset generation failed
8	Android Studio launch failed
9	Resource check failed

Common Issues

Resource Check Failures

# Resource check may find issues but continues build
log_warning "Resource check found issues, but continuing with build..."

Gradle Build Failures

# Check Android SDK and build tools
./android/gradlew --version
# Verify JAVA_HOME is set correctly
echo $JAVA_HOME

Integration with Capacitor

Capacitor Sync Process

# Full sync (all platforms)
npx cap sync

# Android-specific sync
npx cap sync android

Asset Generation

# Generate Android-specific assets
npx capacitor-assets generate --android

Android Studio Integration

# Open Android Studio with project
npx cap open android

Development Workflow

Typical Development Cycle

# 1. Make code changes
# 2. Build for development
npm run build:android:dev

# 3. Open Android Studio for debugging
npm run build:android:studio

# 4. Test on device/emulator
# 5. Iterate and repeat

Testing Workflow

# 1. Build for testing environment
npm run build:android:test

# 2. Build test APK
npm run build:android:test -- --apk

# 3. Install and test on device
adb install android/app/build/outputs/apk/debug/app-debug.apk

Production Workflow

# 1. Build for production environment
npm run build:android:prod

# 2. Build release AAB for Play Store
npm run build:android:prod -- --aab

# 3. Sign and upload to Play Console

Performance Optimization

Build Time Optimization

• Incremental Builds: Gradle caches build artifacts
• Parallel Execution: Multiple build steps run in parallel
• Resource Optimization: Assets are optimized for Android

Memory Management

• Gradle Daemon: Reuses JVM for faster builds
• Build Cache: Caches compiled resources
• Clean Builds: Full cleanup when needed

Troubleshooting

Common Build Issues

Gradle Build Failures

# Clean Gradle cache
cd android && ./gradlew clean && cd ..

# Check Java version
java -version

# Verify Android SDK
echo $ANDROID_HOME

Capacitor Sync Issues

# Force full sync
npx cap sync android --force

# Check Capacitor configuration
cat capacitor.config.json

Asset Generation Issues

# Regenerate assets
npx capacitor-assets generate --android --force

# Check asset source files
ls -la src/assets/

Debug Mode

# Enable verbose logging
./scripts/build-android.sh --verbose

# Show environment variables
./scripts/build-android.sh --env

Best Practices

Build Optimization

1. Use Appropriate Environment: Always specify the correct environment
2. Clean When Needed: Use --clean for troubleshooting
3. Incremental Builds: Avoid unnecessary full rebuilds
4. Asset Management: Keep assets optimized for mobile

Development Workflow

1. Development Builds: Use --dev for daily development
2. Testing Builds: Use --test for QA testing
3. Production Builds: Use --prod for release builds
4. Studio Integration: Use --studio for debugging

Error Prevention

1. Resource Validation: Always run resource checks
2. Environment Consistency: Use consistent environment variables
3. Build Verification: Test builds on actual devices
4. Version Control: Keep build scripts in version control

Migration from Legacy System

Backward Compatibility

The new system maintains full backward compatibility:

# Old command still works (now an alias)
npm run build:capacitor:android

# New commands provide more flexibility
npm run build:android:dev
npm run build:android:test
npm run build:android:prod

Note: All Android builds should use the build:android* pattern. The build:capacitor:android* scripts are provided as aliases for compatibility but will be deprecated in the future.

Migration Checklist

• Update CI/CD pipelines to use new commands
• Update documentation references
• Train team on new build options
• Test all build environments
• Verify artifact locations

Future Enhancements

Planned Features

1. Build Profiles: Custom build configurations
2. Automated Testing: Integration with test suites
3. Build Analytics: Performance metrics and reporting
4. Cloud Builds: Remote build capabilities

Integration Opportunities

1. Fastlane Integration: Automated deployment
2. CI/CD Enhancement: Pipeline optimization
3. Monitoring: Build performance tracking
4. Documentation: Auto-generated build reports

---

Status: Complete and ready for production use Last Updated: 2025-07-11 Version: 1.0 Maintainer: Matthew Raymer