trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Pull Requests 11 Releases 5 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2188 Commits
69 Branches
24 Tags
527 MiB
 
 
 
 
 
 
Tree: 6b0326b582
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6b0326b582'
${ noResults }
crowd-funder-for-time-pwa/docs/build-troubleshooting.md

12 KiB
Raw Blame History

Build Systems Troubleshooting Guide

Author: Matthew Raymer Date: 2025-07-11 Status: ✅ COMPLETE - Comprehensive troubleshooting for all build systems

Overview

This guide provides comprehensive troubleshooting for all TimeSafari build systems, including common issues, solutions, and debugging techniques for web, Android, iOS, and Electron builds.

Quick Diagnostic Commands

Environment Check

# Check Node.js and npm versions
node --version
npm --version

# Check platform-specific tools
npx cap --version
npx vite --version

# Check environment variables
echo $VITE_PLATFORM
echo "PWA: automatically enabled for web platforms"

Build System Status

# Check all build scripts exist
ls -la scripts/build-*.sh

# Check package.json scripts
npm run | grep build:

# Check build artifacts
ls -la dist/
ls -la android/app/build/
ls -la electron/dist/

Web Build Issues

Development Server Problems

Port Already in Use

# Check what's using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use different port
npm run build:web:dev -- --port 8081

Hot Reload Not Working

# Clear browser cache
# DevTools > Application > Storage > Clear site data

# Restart dev server
npm run build:web:dev

# Check file watching
# Ensure no file system watcher limits

PWA Issues in Development

# Clear service worker
# DevTools > Application > Service Workers > Unregister

# Clear browser cache
# DevTools > Application > Storage > Clear site data

# Restart development server
npm run build:web:dev

Production Build Issues

Build Fails with Errors

# Clean build artifacts
rm -rf dist/

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules/
npm install

# Rebuild
npm run build:web:prod

Large Bundle Size

# Analyze bundle
npm run build:web:prod
# Check dist/assets/ for large files

# Enable bundle analysis
npm install --save-dev vite-bundle-analyzer
# Add to vite.config.web.mts

PWA Not Working in Production

# Check manifest generation
ls -la dist/manifest.webmanifest

# Check service worker
ls -la dist/sw.js

# Verify HTTPS (required for PWA)
# Ensure site is served over HTTPS

Docker Build Issues

Docker Build Fails

# Check Docker is running
docker --version
docker ps

# Clean Docker cache
docker system prune -a

# Rebuild without cache
docker build --no-cache -t timesafari-web:production .

Docker Image Too Large

# Use multi-stage builds
# Optimize base images
# Remove unnecessary files

# Analyze image layers
docker history timesafari-web:production

Android Build Issues

Build Process Failures

Gradle Build Fails

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

# Clear Android build cache
rm -rf android/app/build/
rm -rf android/.gradle/

# Rebuild
npm run build:android:dev

Capacitor Sync Issues

# Clean Capacitor
npx cap clean android

# Reinstall Android platform
npx cap remove android
npx cap add android

# Sync manually
npx cap sync android

Resource Generation Fails

# Check source assets
ls -la assets/icon.png
ls -la assets/splash.png

# Regenerate assets
npx capacitor-assets generate --android

# Check generated resources
ls -la android/app/src/main/res/

Device Deployment Issues

No Device Connected

# Check device connection
adb devices

# Enable USB debugging
# Settings > Developer options > USB debugging

# Install ADB drivers (Windows)
# Download from Google USB drivers

Device Unauthorized

# Check device for authorization dialog
# Tap "Allow USB debugging"

# Reset ADB
adb kill-server
adb start-server

# Check device again
adb devices

APK Installation Fails

# Uninstall existing app
adb uninstall app.timesafari.app

# Install fresh APK
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# Check installation
adb shell pm list packages | grep timesafari

Performance Issues

Slow Build Times

# Enable Gradle daemon
# Add to ~/.gradle/gradle.properties:
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.configureondemand=true

# Use incremental builds
# Only rebuild changed files

Large APK Size

# Enable APK splitting
# Add to android/app/build.gradle:
android {
    splits {
        abi {
            enable true
            reset()
            include 'x86', 'x86_64', 'arm64-v8a', 'armeabi-v7a'
        }
    }
}

Electron Build Issues

Development Issues

App Won't Start

# Check Electron installation
npm list electron

# Clear Electron cache
rm -rf ~/.config/TimeSafari/
rm -rf ~/Library/Application\ Support/TimeSafari/
rm -rf %APPDATA%\TimeSafari

# Reinstall Electron
npm install electron

Single Instance Lock Issues

# Check lock file
ls -la ~/.timesafari-lock

# Remove lock file manually
rm -f ~/.timesafari-lock

# Restart app
npm run build:electron:dev

Database Issues

# Clear database
./scripts/clear-database.sh

# Check database files
ls -la ~/.config/TimeSafari/
ls -la ~/Library/Application\ Support/TimeSafari/

# Rebuild database
npm run build:electron:dev

Package Build Issues

Package Creation Fails

# Check electron-builder
npm list electron-builder

# Clean package cache
rm -rf electron/dist/
rm -rf electron/node_modules/

# Reinstall dependencies
cd electron && npm install && cd ..

# Rebuild package
npm run build:electron:appimage:prod

Code Signing Issues

# Check certificates
# macOS: Keychain Access
# Windows: Certificate Manager
# Linux: Check certificate files

# Skip code signing for testing
# Add to electron-builder.config.json:
"forceCodeSigning": false

Platform-Specific Issues

Linux AppImage Issues
# Check AppImage creation
file electron/dist/*.AppImage

# Make executable
chmod +x electron/dist/*.AppImage

# Test AppImage
./electron/dist/*.AppImage
macOS DMG Issues
# Check DMG creation
file electron/dist/*.dmg

# Mount DMG
hdiutil attach electron/dist/*.dmg

# Check contents
ls -la /Volumes/TimeSafari/
Windows EXE Issues
# Check EXE creation
file electron/dist/*.exe

# Test installer
# Run the EXE file
# Check installation directory

iOS Build Issues (Future)

Xcode Issues

# Check Xcode installation
xcode-select --print-path

# Install command line tools
xcode-select --install

# Accept Xcode license
sudo xcodebuild -license accept

Simulator Issues

# List available simulators
xcrun simctl list devices

# Boot simulator
xcrun simctl boot "iPhone 15 Pro"

# Reset simulator
xcrun simctl erase all

Code Signing Issues

# Check certificates
security find-identity -v -p codesigning

# Check provisioning profiles
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Install certificate
# Use Keychain Access or Xcode

Environment Issues

Environment Variables

Missing Environment Variables

# Check environment files
ls -la .env*

# Set required variables
export VITE_PLATFORM=web

# Check in build script
echo $VITE_PLATFORM
echo "PWA: automatically enabled for web platforms"

Wrong Environment Loaded

# Check current environment
echo $NODE_ENV

# Force environment
NODE_ENV=production npm run build:web:prod

# Check environment file loading
# Verify .env.production exists

Dependency Issues

Missing Dependencies

# Check package.json
cat package.json | grep -A 10 "dependencies"

# Install missing dependencies
npm install

# Check for peer dependencies
npm ls

Version Conflicts

# Check for conflicts
npm ls

# Update dependencies
npm update

# Force resolution
npm install --force

Platform-Specific Dependencies

# Check Capacitor plugins
npx cap ls

# Install missing plugins
npm install @capacitor/core @capacitor/cli

# Sync plugins
npx cap sync

Performance Issues

Build Performance

Slow Build Times

# Enable parallel processing
# Add to package.json scripts:
"build:parallel": "npm run build:web:prod & npm run build:android:prod & wait"

# Use incremental builds
# Only rebuild changed files

# Optimize file watching
# Increase file watcher limits

Memory Issues

# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" npm run build:web:prod

# Check memory usage
top -p $(pgrep node)

# Optimize build process
# Use streaming builds
# Minimize memory usage

Runtime Performance

App Performance Issues

# Profile application
# Use browser DevTools > Performance
# Use React/Vue DevTools

# Check bundle size
npm run build:web:prod
# Analyze dist/assets/

# Optimize code splitting
# Implement lazy loading

Debugging Techniques

Verbose Logging

Enable Verbose Mode

# Web builds
./scripts/build-web.sh --verbose

# Android builds
./scripts/build-android.sh --verbose

# Electron builds
./scripts/build-electron.sh --verbose

Debug Environment

# Enable debug logging
DEBUG_MIGRATIONS=1 npm run build:web:dev

# Check debug output
# Look for detailed error messages
# Check console output

Log Analysis

Build Logs

# Capture build logs
npm run build:web:prod > build.log 2>&1

# Analyze logs
grep -i error build.log
grep -i warning build.log

# Check for specific issues
grep -i "failed\|error\|exception" build.log

Runtime Logs

Web Browser
# Open DevTools
# Console tab for JavaScript errors
# Network tab for API issues
# Application tab for storage issues
Android
# View Android logs
adb logcat | grep -i timesafari

# Filter by app
adb logcat | grep -i "app.timesafari.app"
Electron
# View Electron logs
# Check console output
# Check DevTools console
# Check main process logs

Common Error Messages

Web Build Errors

"Module not found"

# Check import paths
# Verify file exists
# Check case sensitivity
# Update import statements

"Port already in use"

# Kill existing process
lsof -i :8080
kill -9 <PID>

# Use different port
npm run build:web:dev -- --port 8081

Android Build Errors

"Gradle build failed"

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

# Check Gradle version
./android/gradlew --version

# Update Gradle wrapper
cd android && ./gradlew wrapper --gradle-version 8.13 && cd ..

"Device not found"

# Check device connection
adb devices

# Enable USB debugging
# Settings > Developer options > USB debugging

# Install drivers (Windows)
# Download Google USB drivers

Electron Build Errors

"App already running"

# Remove lock file
rm -f ~/.timesafari-lock

# Kill existing processes
pkill -f "TimeSafari"

# Restart app
npm run build:electron:dev

"Code signing failed"

# Check certificates
# macOS: Keychain Access
# Windows: Certificate Manager

# Skip code signing for testing
# Add to electron-builder.config.json:
"forceCodeSigning": false

Prevention Strategies

Best Practices

Regular Maintenance

# Update dependencies regularly
npm update

# Clean build artifacts
npm run clean:all

# Check for security vulnerabilities
npm audit

# Update build tools
npm update -g @capacitor/cli
npm update -g electron-builder

Environment Management

# Use consistent environments
# Separate dev/test/prod configurations
# Version control environment files
# Document environment requirements

Testing

# Test builds regularly
npm run build:web:prod
npm run build:android:prod
npm run build:electron:prod

# Test on different platforms
# Verify all features work
# Check performance metrics

Monitoring

Build Monitoring

# Track build times
# Monitor build success rates
# Check for performance regressions
# Monitor bundle sizes

Runtime Monitoring

# Monitor app performance
# Track error rates
# Monitor user experience
# Check platform-specific issues

Last Updated: 2025-07-11 Version: 1.0.3-beta Status: Production Ready