docs: comprehensive build system documentation overhaul

- Expand BUILDING.md with detailed platform-specific build commands and workflows
- Add comprehensive web build script documentation with environment modes and Docker support
- Include complete iOS/Android build command reference with auto-run capabilities
- Document Electron build patterns with code signing and packaging instructions
- Add troubleshooting sections for common build issues across platforms
- Streamline README.md by removing redundant build system details
- Include build architecture overview with service worker and environment configuration
- Add comprehensive npm script reference for all build operations
- Document auto-run system and platform-specific testing workflows
- Include security considerations and code signing procedures for distribution

Improves developer experience with complete build system documentation and reduces onboarding friction for new contributors.
This commit is contained in:
Matthew Raymer
2025-07-15 10:17:34 +00:00
parent fdf722572b
commit e106af4b98
2 changed files with 633 additions and 199 deletions

View File

@@ -45,7 +45,7 @@ npm install
npm run dev
```
See [BUILDING.md](BUILDING.md) for more details.
See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker).
## Development Database Clearing
@@ -107,99 +107,6 @@ rm -rf ~/timesafari-dev-data
See the script for complete platform-specific instructions.
## Build Systems
TimeSafari supports comprehensive build systems for all platforms with unified patterns and consistent tooling.
### **Quick Start Commands**
```bash
# Web Development (starts dev server)
npm run build:web:dev
# Android Development (builds debug APK)
npm run build:android:dev
# iOS Development (builds debug app)
npm run build:ios:dev
# Electron Development (runs app directly)
npm run build:electron:dev
# Deploy Android to connected device
npm run build:android:deploy
# Deploy iOS to connected device
npm run build:ios:deploy
```
### **Platform-Specific Builds**
#### **Web Builds**
- **Development**: Hot reload server at http://localhost:8080
- **Production**: Optimized static files with PWA support
- **Docker**: Containerized deployment images
```bash
npm run build:web:dev # Development server
npm run build:web:prod # Production build
npm run build:web:docker:prod # Docker deployment
```
#### **Android Builds**
- **Development**: Debug APK with development optimizations
- **Production**: Release APK/AAB for app store distribution
- **Deployment**: Direct installation to connected devices
```bash
npm run build:android:dev # Development build
npm run build:android:prod # Production build
npm run build:android:deploy # Build and deploy to device
```
#### **iOS Builds**
- **Development**: Debug app with development optimizations
- **Production**: Release app/IPA for app store distribution
- **Deployment**: Direct installation to connected devices
```bash
npm run build:ios:dev # Development build
npm run build:ios:prod # Production build
npm run build:ios:deploy # Build and deploy to device
```
#### **Electron Builds**
- **Development**: Runs app directly for development
- **Packages**: Creates distributable executables
- **Cross-Platform**: Windows, macOS, Linux support
```bash
npm run build:electron:dev # Runs app directly
npm run build:electron:appimage:prod # Linux AppImage
npm run build:electron:dmg:prod # macOS DMG
npm run build:electron:deb:prod # Linux DEB
```
### **Build System Features**
-**Unified Environment Management**: Consistent dev/test/prod modes
-**PWA Support**: Progressive Web App functionality across platforms
-**Asset Generation**: Automatic icon and splash screen generation
-**Docker Integration**: Containerized deployment options
-**Performance Optimization**: Build-time and runtime optimizations
-**Error Handling**: Comprehensive error reporting and recovery
-**Legacy Compatibility**: Backward-compatible script aliases
### **Comprehensive Documentation**
- **[Build Systems Overview](docs/build-systems-overview.md)** - Complete guide to all build systems
- **[Web Build Scripts](docs/web-build-scripts.md)** - Web/PWA builds with Docker support
- **[Android Build Scripts](docs/android-build-scripts.md)** - Mobile builds with device deployment
- **[iOS Build Scripts](docs/ios-build-scripts.md)** - iOS builds with Xcode integration
- **[Electron Build Scripts](docs/electron-build-scripts.md)** - Desktop builds with package creation
- **[Database Clearing](docs/database-clearing.md)** - Development database management
- **[Build Troubleshooting](docs/build-troubleshooting.md)** - Comprehensive troubleshooting guide
## Tests
See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
@@ -252,7 +159,6 @@ The application uses a platform-agnostic database layer with Vue mixins for serv
**Development Guidelines**:
- Always use `PlatformServiceMixin` for database operations in components
- Never import Dexie directly in application code
- Test with PlatformServiceMixin for new features
- Use migration tools for data transfer between systems
- Leverage mixin's ultra-concise methods: `$db()`, `$exec()`, `$one()`, `$contacts()`, `$settings()`