7.1 KiB

Raw Blame History

Android Asset Validation System

Author: Matthew Raymer
Date: 2025-08-22
Status: 🎯 ACTIVE - Production Ready

Overview

The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons.

Problem Solved

Previously, Android builds would fail with errors like:

error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found.
error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found.

This happened when:

Source assets existed but weren't generated into Android resources
Android resource directories were missing
Asset generation tools weren't run before building

Solution

Enhanced Build Script Validation

The scripts/build-android.sh script now includes comprehensive asset validation that:

Checks Source Assets: Validates that required source files exist in resources/
Checks Android Resources: Verifies that generated Android resources exist
Auto-Regenerates: Automatically regenerates missing resources when detected
Verifies Results: Confirms that regeneration was successful

Validation Process

# Validates and regenerates if needed
npm run assets:validate:android

# Full build with validation
npm run build:android:studio

What Gets Validated

Source Assets (Required)

resources/icon.png - App icon source
resources/splash.png - Splash screen source
resources/splash_dark.png - Dark mode splash source

Android Resources (Generated)

android/app/src/main/res/drawable/splash.png - Splash screen drawable
android/app/src/main/res/mipmap-*/ic_launcher.png - App icons for all densities
android/app/src/main/res/mipmap-*/ic_launcher_round.png - Round app icons for all densities

Density Levels Checked

mipmap-mdpi (1x)
mipmap-hdpi (1.5x)
mipmap-xhdpi (2x)
mipmap-xxhdpi (3x)
mipmap-xxxhdpi (4x)

Usage

Automatic Validation (Recommended)

The validation runs automatically during all Android builds:

# Development build with validation
npm run build:android:studio

# Production build with validation  
npm run build:android:prod

# Debug build with validation
npm run build:android:debug

Manual Validation

Run validation only to check/fix assets:

# Validate and regenerate if needed
npm run assets:validate:android

# Alternative command
./scripts/build-android.sh --assets-only

Validation Only (No Regeneration)

Check configuration without fixing:

npm run assets:validate

Error Handling

Missing Source Assets

If source assets are missing, the build fails with clear error messages:

[ERROR] Missing source assets:
[ERROR]   - resources/icon.png
[ERROR]   - resources/splash.png
[ERROR] Please ensure all required assets are present in the resources/ directory.

Missing Generated Resources

If generated resources are missing, they're automatically regenerated:

[WARN] Missing Android resources detected:
[WARN]   - drawable/splash.png
[WARN]   - mipmap-mdpi/ic_launcher.png
[INFO] Regenerating Android assets...
[SUCCESS] Android assets regenerated successfully

Generation Failure

If regeneration fails, helpful guidance is provided:

[ERROR] Failed to generate Android assets
[INFO] You may need to manually create the missing resources:
[INFO]   - android/app/src/main/res/drawable/splash.png
[INFO]   - android/app/src/main/res/mipmap-mdpi/ic_launcher.png

Integration Points

Build Script Integration

The validation is integrated into the main build process:

# In scripts/build-android.sh
validate_dependencies
validate_android_assets || {
    log_error "Android asset validation failed. Please fix the issues above and try again."
    exit 9
}

NPM Scripts

New npm scripts for asset management:

{
  "assets:validate": "npx tsx scripts/assets-validator.ts",
  "assets:validate:android": "./scripts/build-android.sh --assets-only",
  "assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true"
}

Benefits

For Developers

No More Build Failures: Automatic detection and fixing of missing resources
Faster Development: No need to manually run asset generation tools
Clear Error Messages: Helpful guidance when issues occur
Consistent Results: Same validation on all development machines

For CI/CD

Reliable Builds: Consistent asset validation across environments
Early Detection: Catches issues before they reach production
Automated Fixes: Self-healing builds when possible

For Project Maintenance

Reduced Support: Fewer "build doesn't work" issues
Documentation: Clear requirements for required assets
Standardization: Consistent asset structure across the project

Troubleshooting

Common Issues

"No assets found in the asset path"

This occurs when the assets/ directory is empty. The validation system automatically copies source assets and regenerates them.

"Failed to generate Android assets"

Check that:

Source assets exist in resources/
@capacitor/assets is installed
You have write permissions to the Android directories

"Asset generation completed but some resources are still missing"

This indicates a problem with the asset generation tool. Try:

Running npm install to ensure dependencies are up to date
Manually running npx @capacitor/assets generate
Checking the asset generation logs for specific errors

Manual Recovery

If automatic regeneration fails, you can manually create the missing resources:

# Create missing directories
mkdir -p android/app/src/main/res/drawable
mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}

# Copy source assets to assets directory
cp resources/icon.png assets/
cp resources/splash.png assets/
cp resources/splash_dark.png assets/

# Generate assets manually
npx @capacitor/assets generate

# Clean up
rm assets/icon.png assets/splash.png assets/splash_dark.png

Future Enhancements

Planned Improvements

iOS Asset Validation: Extend validation to iOS assets
Asset Quality Checks: Validate image dimensions and formats
Performance Optimization: Cache validation results
CI/CD Integration: Add validation to GitHub Actions

Configuration Options

Custom Asset Paths: Support for different asset directory structures
Validation Rules: Configurable validation requirements
Skip Options: Ability to skip validation for specific scenarios

References

Status: Active validation system
Priority: High
Maintainer: Development team
Next Review: 2025-09-22

7.1 KiB Raw Blame History