forked from jsnbuchanan/crowd-funder-for-time-pwa
docs: reorganize documentation structure with 7-item folder limits
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
This commit is contained in:
Matthew Raymer
616
docs/build-system/core/build-pattern-conversion-plan.md
Normal file
616
docs/build-system/core/build-pattern-conversion-plan.md
Normal file
@@ -0,0 +1,616 @@
|
||||
# Build Pattern Conversion Plan
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-07-09
|
||||
**Status**: **PLANNING** - Ready for Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
Convert TimeSafari's build instruction pattern from the current script-based
|
||||
approach to a new Vite `mode`-based pattern that provides better environment
|
||||
management and consistency across all build targets.
|
||||
|
||||
## Why Vite Mode Instead of NODE_ENV?
|
||||
|
||||
### Vite's Native Mode System
|
||||
|
||||
Vite is designed to work with `mode`, which:
|
||||
|
||||
- Determines the `.env` file to load (e.g. `.env.production`, `.env.test`, etc.)
|
||||
- Is passed to `defineConfig(({ mode }) => {...})` in `vite.config.ts`
|
||||
- Is used to set behavior for dev/prod/test at config level
|
||||
- Provides better integration with Vite's build system
|
||||
|
||||
### NODE_ENV Limitations
|
||||
|
||||
`NODE_ENV` is legacy from Webpack-era tooling:
|
||||
|
||||
- You can't change `NODE_ENV` manually and expect Vite to adapt
|
||||
- Vite does not map `NODE_ENV` back to `mode`
|
||||
- It's redundant with `mode` and might conflict with assumptions
|
||||
- Limited integration with Vite's environment loading system
|
||||
|
||||
### Usage Pattern
|
||||
|
||||
```bash
|
||||
# Correct: Use Vite's mode system
|
||||
vite build --mode production
|
||||
vite build --mode development
|
||||
vite build --mode test
|
||||
|
||||
# Only if third-party libraries require NODE_ENV
|
||||
NODE_ENV=production vite build --mode production
|
||||
```
|
||||
|
||||
### Development vs Build Environments
|
||||
|
||||
**Development Environment:**
|
||||
|
||||
- **Build with defaults**: `npm run build:*` - Uses `--mode development` by default
|
||||
- **Purpose**: Development builds for testing and debugging
|
||||
- **Output**: Bundled files with development optimizations
|
||||
|
||||
**Testing/Production Environments:**
|
||||
|
||||
- **Build with explicit mode**: `npm run build:* -- --mode test/production`
|
||||
- **Purpose**: Validate and deploy the bundled application
|
||||
- **Output**: Optimized, bundled files for specific environment
|
||||
|
||||
### Mode Override Behavior
|
||||
|
||||
**How `--mode` Override Works:**
|
||||
|
||||
```bash
|
||||
# Base script (no hardcoded mode)
|
||||
"build:electron": "vite build --config vite.config.electron.mts"
|
||||
|
||||
# Development (uses Vite's default: --mode development)
|
||||
npm run build:electron
|
||||
# Executes: vite build --config vite.config.electron.mts
|
||||
|
||||
# Testing (explicitly overrides with --mode test)
|
||||
npm run build:electron -- --mode test
|
||||
# Executes: vite build --config vite.config.electron.mts --mode test
|
||||
|
||||
# Production (explicitly overrides with --mode production)
|
||||
npm run build:electron -- --mode production
|
||||
# Executes: vite build --config vite.config.electron.mts --mode production
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
|
||||
- Base scripts have **no hardcoded `--mode`** to allow override
|
||||
- `npm run build:electron` defaults to `--mode development`
|
||||
- `npm run build:electron -- --mode test` overrides to `--mode test`
|
||||
- Vite uses the **last `--mode` argument** if multiple are provided
|
||||
|
||||
### Capacitor Platform-Specific Commands
|
||||
|
||||
Capacitor requires platform-specific sync commands after building:
|
||||
|
||||
```bash
|
||||
# General sync (copies web assets to all platforms)
|
||||
npm run build:capacitor && npx cap sync
|
||||
|
||||
# Platform-specific sync
|
||||
npm run build:capacitor && npx cap sync android
|
||||
npm run build:capacitor && npx cap sync ios
|
||||
|
||||
# Environment-specific with platform sync
|
||||
npm run build:capacitor -- --mode production && npx cap sync android
|
||||
npm run build:capacitor -- --mode development && npx cap sync ios
|
||||
```
|
||||
|
||||
### Docker Build Commands
|
||||
|
||||
Docker builds include both Vite asset generation and Docker image creation:
|
||||
|
||||
```bash
|
||||
# General Docker build (Vite build + Docker image)
|
||||
npm run build:web:docker
|
||||
|
||||
# Environment-specific Docker builds
|
||||
npm run build:web:docker:test # Test environment + Docker image
|
||||
npm run build:web:docker:prod # Production environment + Docker image
|
||||
|
||||
# Manual mode overrides for Docker builds
|
||||
npm run build:web:docker -- --mode test
|
||||
npm run build:web:docker -- --mode production
|
||||
```
|
||||
|
||||
**Docker Build Process:**
|
||||
|
||||
1. **Vite Build**: Creates optimized web assets with environment-specific variables
|
||||
2. **Docker Build**: Creates Docker image using `Dockerfile` in project root
|
||||
3. **Image Tagging**: Images are tagged as `timesafari-web` for consistent management
|
||||
|
||||
**Key Features:**
|
||||
|
||||
- Complete end-to-end Docker workflow in single command
|
||||
- Environment-aware builds (test/production configurations)
|
||||
- Consistent image tagging for deployment
|
||||
- Mode override flexibility for custom environments
|
||||
|
||||
### Electron Platform-Specific Commands
|
||||
|
||||
Electron requires platform-specific build commands after the Vite build:
|
||||
|
||||
```bash
|
||||
# General Electron build (Vite build only)
|
||||
npm run build:electron
|
||||
|
||||
# Platform-specific builds
|
||||
npm run build:electron:windows # Windows executable
|
||||
npm run build:electron:mac # macOS app bundle
|
||||
npm run build:electron:linux # Linux executable
|
||||
|
||||
# Package-specific builds
|
||||
npm run build:electron:appimage # Linux AppImage
|
||||
npm run build:electron:dmg # macOS DMG installer
|
||||
|
||||
# Environment-specific builds
|
||||
npm run build:electron -- --mode development
|
||||
npm run build:electron -- --mode test
|
||||
npm run build:electron -- --mode production
|
||||
|
||||
# Environment-specific with platform builds
|
||||
npm run build:electron:windows -- --mode development
|
||||
npm run build:electron:windows -- --mode test
|
||||
npm run build:electron:windows -- --mode production
|
||||
|
||||
npm run build:electron:mac -- --mode development
|
||||
npm run build:electron:mac -- --mode test
|
||||
npm run build:electron:mac -- --mode production
|
||||
|
||||
npm run build:electron:linux -- --mode development
|
||||
npm run build:electron:linux -- --mode test
|
||||
npm run build:electron:linux -- --mode production
|
||||
|
||||
# Environment-specific with package builds
|
||||
npm run build:electron:appimage -- --mode development
|
||||
npm run build:electron:appimage -- --mode test
|
||||
npm run build:electron:appimage -- --mode production
|
||||
|
||||
npm run build:electron:dmg -- --mode development
|
||||
npm run build:electron:dmg -- --mode test
|
||||
npm run build:electron:dmg -- --mode production
|
||||
```
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### Existing Build Scripts
|
||||
|
||||
- **Web**: `build:web` - Uses vite.config.web.mts
|
||||
- **Capacitor**: `build:capacitor` - Uses vite.config.capacitor.mts
|
||||
- **Android**: `build:android` - Shell script wrapper
|
||||
- **iOS**: `build:ios` - Shell script wrapper
|
||||
- **Electron**: `build:electron` - Uses vite.config.electron.mts
|
||||
- **Windows**: `build:electron:windows` - Windows executable
|
||||
- **macOS**: `build:electron:mac` - macOS app bundle
|
||||
- **Linux**: `build:electron:linux` - Linux executable
|
||||
- **AppImage**: `build:electron:appimage` - Linux AppImage
|
||||
- **DMG**: `build:electron:dmg` - macOS DMG installer
|
||||
|
||||
### Current `package.json` Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"build:capacitor": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode capacitor --config vite.config.capacitor.mts",
|
||||
"build:web": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.web.mts",
|
||||
"build:electron": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode electron --config vite.config.electron.mts"
|
||||
}
|
||||
```
|
||||
|
||||
## Target Pattern
|
||||
|
||||
### New Vite Mode-Based Pattern
|
||||
|
||||
```bash
|
||||
# Development builds (defaults to --mode development)
|
||||
npm run build:web-dev
|
||||
npm run build:capacitor-dev
|
||||
npm run build:electron-dev
|
||||
|
||||
# Testing builds (bundle required)
|
||||
npm run build:web -- --mode test
|
||||
npm run build:capacitor -- --mode test && npx cap sync
|
||||
npm run build:electron -- --mode test
|
||||
|
||||
# Production builds (bundle required)
|
||||
npm run build:web -- --mode production
|
||||
npm run build:capacitor -- --mode production && npx cap sync
|
||||
npm run build:electron -- --mode production
|
||||
|
||||
# Docker builds
|
||||
npm run build:web:docker -- --mode test
|
||||
npm run build:web:docker -- --mode production
|
||||
|
||||
# Docker environment-specific builds
|
||||
npm run build:web:docker:test
|
||||
npm run build:web:docker:prod
|
||||
|
||||
# Capacitor platform-specific builds
|
||||
npm run build:capacitor:android -- --mode test
|
||||
npm run build:capacitor:android -- --mode production
|
||||
|
||||
npm run build:capacitor:ios -- --mode test
|
||||
npm run build:capacitor:ios -- --mode production
|
||||
|
||||
# Electron platform-specific builds
|
||||
npm run build:electron:windows -- --mode test
|
||||
npm run build:electron:windows -- --mode production
|
||||
|
||||
npm run build:electron:mac -- --mode test
|
||||
npm run build:electron:mac -- --mode production
|
||||
|
||||
npm run build:electron:linux -- --mode test
|
||||
npm run build:electron:linux -- --mode production
|
||||
|
||||
# Electron package-specific builds
|
||||
npm run build:electron:appimage -- --mode test
|
||||
npm run build:electron:appimage -- --mode production
|
||||
|
||||
npm run build:electron:dmg -- --mode test
|
||||
npm run build:electron:dmg -- --mode production
|
||||
```
|
||||
|
||||
### New `package.json` Scripts Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"build:web": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite --mode development --config vite.config.web.mts",
|
||||
"build:web:dev": "npm run build:web",
|
||||
"build:web:build": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode development --config vite.config.web.mts",
|
||||
"build:web:test": "npm run build:web:build -- --mode test",
|
||||
"build:web:prod": "npm run build:web:build -- --mode production",
|
||||
"build:web:docker": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.web.mts && docker build -t timesafari-web .",
|
||||
"build:web:docker:test": "npm run build:web:docker -- --mode test",
|
||||
"build:web:docker:prod": "npm run build:web:docker -- --mode production",
|
||||
|
||||
"build:capacitor": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode capacitor --config vite.config.capacitor.mts",
|
||||
"build:capacitor-dev": "npm run build:capacitor",
|
||||
"build:capacitor:sync": "npm run build:capacitor && npx cap sync",
|
||||
"build:capacitor:android": "npm run build:capacitor:sync && npx cap sync android",
|
||||
"build:capacitor:ios": "npm run build:capacitor:sync && npx cap sync ios",
|
||||
|
||||
"build:electron": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.electron.mts",
|
||||
"build:electron:dev": "npm run build:electron && cd electron && npm run electron:start",
|
||||
"build:electron:windows": "npm run build:electron && cd electron && npm run build:windows",
|
||||
"build:electron:mac": "npm run build:electron && cd electron && npm run build:mac",
|
||||
"build:electron:linux": "npm run build:electron && cd electron && npm run build:linux",
|
||||
"build:electron:appimage": "npm run build:electron:linux && cd electron && npm run build:appimage",
|
||||
"build:electron:dmg": "npm run build:electron:mac && cd electron && npm run build:dmg"
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Environment Configuration (Day 1)
|
||||
|
||||
#### 1.1 Update Vite Configurations
|
||||
|
||||
- [ ] **vite.config.web.mts**: Add mode-based configuration
|
||||
- [ ] **vite.config.capacitor.mts**: Add mode-based configuration
|
||||
- [ ] **vite.config.electron.mts**: Add mode-based configuration
|
||||
- [ ] **vite.config.common.mts**: Add environment-specific variables
|
||||
|
||||
#### 1.2 Environment Variables Setup
|
||||
|
||||
- [ ] Create `.env.development` file for development settings
|
||||
- [ ] Create `.env.test` file for testing settings
|
||||
- [ ] Create `.env.production` file for production settings
|
||||
- [ ] Update `.env.example` with new pattern
|
||||
|
||||
#### 1.3 Environment Detection Logic
|
||||
|
||||
```typescript
|
||||
// vite.config.common.mts
|
||||
export default defineConfig(({ mode }) => {
|
||||
const getEnvironmentConfig = (mode: string) => {
|
||||
switch (mode) {
|
||||
case 'production':
|
||||
return { /* production settings */ };
|
||||
case 'test':
|
||||
return { /* testing settings */ };
|
||||
default:
|
||||
return { /* development settings */ };
|
||||
}
|
||||
};
|
||||
|
||||
return {
|
||||
define: {
|
||||
__DEV__: mode === 'development',
|
||||
__TEST__: mode === 'test',
|
||||
__PROD__: mode === 'production'
|
||||
},
|
||||
// ... other config
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 2: Package.json Scripts Update (Day 1)
|
||||
|
||||
#### 2.1 Web Build Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"build:web": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.web.mts",
|
||||
"build:web-dev": "npm run build:web",
|
||||
"build:web-test": "npm run build:web -- --mode test",
|
||||
"build:web-prod": "npm run build:web -- --mode production"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.2 Capacitor Build Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"build:capacitor": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode capacitor --config vite.config.capacitor.mts",
|
||||
"build:capacitor-dev": "npm run build:capacitor",
|
||||
"build:capacitor:sync": "npm run build:capacitor && npx cap sync",
|
||||
"build:capacitor:android": "npm run build:capacitor:sync && npx cap sync android",
|
||||
"build:capacitor:ios": "npm run build:capacitor:sync && npx cap sync ios",
|
||||
"build:capacitor-test": "npm run build:capacitor -- --mode test && npx cap sync",
|
||||
"build:capacitor-prod": "npm run build:capacitor -- --mode production && npx cap sync",
|
||||
"build:capacitor:android-test": "npm run build:capacitor -- --mode test && npx cap sync android",
|
||||
"build:capacitor:android-prod": "npm run build:capacitor -- --mode production && npx cap sync android",
|
||||
"build:capacitor:ios-test": "npm run build:capacitor -- --mode test && npx cap sync ios",
|
||||
"build:capacitor:ios-prod": "npm run build:capacitor -- --mode production && npx cap sync ios"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.3 Electron Build Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"build:electron": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.electron.mts",
|
||||
"build:electron-dev": "npm run build:electron",
|
||||
"build:electron:windows": "npm run build:electron && cd electron && npm run build:windows",
|
||||
"build:electron:mac": "npm run build:electron && cd electron && npm run build:mac",
|
||||
"build:electron:linux": "npm run build:electron && cd electron && npm run build:linux",
|
||||
"build:electron:appimage": "npm run build:electron:linux && cd electron && npm run build:appimage",
|
||||
"build:electron:dmg": "npm run build:electron:mac && cd electron && npm run build:dmg",
|
||||
"build:electron-test": "npm run build:electron -- --mode test",
|
||||
"build:electron-prod": "npm run build:electron -- --mode production",
|
||||
"build:electron:windows-test": "npm run build:electron -- --mode test && cd electron && npm run build:windows",
|
||||
"build:electron:windows-prod": "npm run build:electron -- --mode production && cd electron && npm run build:windows",
|
||||
"build:electron:mac-dev": "npm run build:electron -- --mode development && cd electron && npm run build:mac",
|
||||
"build:electron:mac-test": "npm run build:electron -- --mode test && cd electron && npm run build:mac",
|
||||
"build:electron:mac-prod": "npm run build:electron -- --mode production && cd electron && npm run build:mac",
|
||||
"build:electron:linux-test": "npm run build:electron -- --mode test && cd electron && npm run build:linux",
|
||||
"build:electron:linux-prod": "npm run build:electron -- --mode production && cd electron && npm run build:linux"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.4 Docker Build Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"build:web:docker": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.web.mts && docker build -t timesafari-web .",
|
||||
"build:web:docker:test": "npm run build:web:docker -- --mode test",
|
||||
"build:web:docker:prod": "npm run build:web:docker -- --mode production"
|
||||
}
|
||||
```
|
||||
|
||||
**Docker Build Features:**
|
||||
|
||||
- Complete Vite build + Docker image creation workflow
|
||||
- Environment-specific configurations (test/production)
|
||||
- Consistent image tagging (`timesafari-web`)
|
||||
- Mode override flexibility for custom environments
|
||||
|
||||
### Phase 3: Shell Script Updates (Day 2)
|
||||
|
||||
#### 3.1 Update build-electron.sh
|
||||
|
||||
- [ ] Add mode-based environment support
|
||||
- [ ] Update environment loading logic
|
||||
- [ ] Add environment-specific build paths
|
||||
- [ ] Update logging to show environment
|
||||
|
||||
#### 3.2 Update build-android.sh
|
||||
|
||||
- [ ] Add mode-based environment support
|
||||
- [ ] Update environment detection
|
||||
- [ ] Add environment-specific configurations
|
||||
|
||||
#### 3.3 Update build-ios.sh
|
||||
|
||||
- [ ] Add mode-based environment support
|
||||
- [ ] Update environment detection
|
||||
- [ ] Add environment-specific configurations
|
||||
|
||||
### Phase 4: Documentation Updates (Day 2)
|
||||
|
||||
#### 4.1 Update BUILDING.md
|
||||
|
||||
- [ ] Document new Vite mode-based pattern
|
||||
- [ ] Update build instructions
|
||||
- [ ] Add environment-specific examples
|
||||
- [ ] Update troubleshooting section
|
||||
|
||||
#### 4.2 Update scripts/README.md
|
||||
|
||||
- [ ] Document new Vite mode-based build patterns
|
||||
- [ ] Update usage examples
|
||||
- [ ] Add environment configuration guide
|
||||
|
||||
#### 4.3 Update CI/CD Documentation
|
||||
|
||||
- [ ] Update GitHub Actions workflows
|
||||
- [ ] Update Docker build instructions
|
||||
- [ ] Update deployment guides
|
||||
|
||||
### Phase 5: Testing & Validation (Day 3)
|
||||
|
||||
#### 5.1 Environment Testing
|
||||
|
||||
- [ ] Test dev environment builds
|
||||
- [ ] Test test environment builds
|
||||
- [ ] Test prod environment builds
|
||||
- [ ] Validate environment variables
|
||||
|
||||
#### 5.2 Platform Testing
|
||||
|
||||
- [ ] Test web builds across environments
|
||||
- [ ] Test capacitor builds across environments
|
||||
- [ ] Test capacitor android sync across environments
|
||||
- [ ] Test capacitor ios sync across environments
|
||||
- [ ] Test electron builds across environments
|
||||
- [ ] Test electron windows builds across environments
|
||||
- [ ] Test electron mac builds across environments
|
||||
- [ ] Test electron linux builds across environments
|
||||
- [ ] Test electron appimage builds across environments
|
||||
- [ ] Test electron dmg builds across environments
|
||||
- [ ] Test docker builds across environments
|
||||
- [ ] Test docker image creation and tagging
|
||||
- [ ] Test docker environment-specific configurations
|
||||
|
||||
#### 5.3 Integration Testing
|
||||
|
||||
- [ ] Test with existing CI/CD pipelines
|
||||
- [ ] Test with existing deployment scripts
|
||||
- [ ] Test with existing development workflows
|
||||
|
||||
## Environment-Specific Configurations
|
||||
|
||||
### Development Environment (--mode development)
|
||||
|
||||
```typescript
|
||||
{
|
||||
VITE_API_URL: 'http://localhost:3000',
|
||||
VITE_DEBUG: 'true',
|
||||
VITE_LOG_LEVEL: 'debug',
|
||||
VITE_ENABLE_DEV_TOOLS: 'true'
|
||||
}
|
||||
```
|
||||
|
||||
### Testing Environment (--mode test)
|
||||
|
||||
```typescript
|
||||
{
|
||||
VITE_API_URL: 'https://test-api.timesafari.com',
|
||||
VITE_DEBUG: 'false',
|
||||
VITE_LOG_LEVEL: 'info',
|
||||
VITE_ENABLE_DEV_TOOLS: 'false'
|
||||
}
|
||||
```
|
||||
|
||||
### Production Environment (--mode production)
|
||||
|
||||
```typescript
|
||||
{
|
||||
VITE_API_URL: 'https://api.timesafari.com',
|
||||
VITE_DEBUG: 'false',
|
||||
VITE_LOG_LEVEL: 'warn',
|
||||
VITE_ENABLE_DEV_TOOLS: 'false'
|
||||
}
|
||||
```
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
- [ ] Keep existing script names as aliases
|
||||
- [ ] Add deprecation warnings for old scripts
|
||||
- [ ] Maintain existing CI/CD compatibility
|
||||
- [ ] Provide migration guide for users
|
||||
|
||||
### Gradual Rollout
|
||||
|
||||
1. **Week 1**: Implement new scripts alongside existing ones
|
||||
2. **Week 2**: Update CI/CD to use new pattern
|
||||
3. **Week 3**: Update documentation and guides
|
||||
4. **Week 4**: Deprecate old scripts with warnings
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Technical Metrics
|
||||
|
||||
- [ ] All builds work with Vite mode-based pattern
|
||||
- [ ] Environment variables properly loaded
|
||||
- [ ] Build artifacts correctly generated
|
||||
- [ ] No regression in existing functionality
|
||||
|
||||
### Process Metrics
|
||||
|
||||
- [ ] Reduced build script complexity
|
||||
- [ ] Improved environment management
|
||||
- [ ] Better developer experience
|
||||
- [ ] Consistent build patterns
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Low Risk
|
||||
|
||||
- [ ] Environment variable changes
|
||||
- [ ] Package.json script updates
|
||||
- [ ] Documentation updates
|
||||
|
||||
### Medium Risk
|
||||
|
||||
- [ ] Vite configuration changes (mode-based)
|
||||
- [ ] Shell script modifications
|
||||
- [ ] CI/CD pipeline updates
|
||||
|
||||
### High Risk
|
||||
|
||||
- [ ] Breaking existing build processes
|
||||
- [ ] Environment-specific bugs
|
||||
- [ ] Deployment failures
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
### Immediate Rollback
|
||||
|
||||
- [ ] Revert package.json changes
|
||||
- [ ] Restore original vite configs
|
||||
- [ ] Restore original shell scripts
|
||||
|
||||
### Gradual Rollback
|
||||
|
||||
- [ ] Keep old scripts as primary
|
||||
- [ ] Use new scripts as experimental
|
||||
- [ ] Gather feedback before full migration
|
||||
|
||||
## Timeline
|
||||
|
||||
### Day 1: Foundation
|
||||
|
||||
- [ ] Environment configuration setup
|
||||
- [ ] Package.json script updates
|
||||
- [ ] Basic testing
|
||||
|
||||
### Day 2: Integration
|
||||
|
||||
- [ ] Shell script updates
|
||||
- [ ] Documentation updates
|
||||
- [ ] Integration testing
|
||||
|
||||
### Day 3: Validation
|
||||
|
||||
- [ ] Comprehensive testing
|
||||
- [ ] Performance validation
|
||||
- [ ] Documentation review
|
||||
|
||||
### Day 4: Deployment
|
||||
|
||||
- [ ] CI/CD updates
|
||||
- [ ] Production validation
|
||||
- [ ] User communication
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review and approve plan**
|
||||
2. **Set up development environment**
|
||||
3. **Begin Phase 1 implementation**
|
||||
4. **Create test cases**
|
||||
5. **Start implementation**
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for implementation
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: 3-4 days
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team, DevOps team
|
||||
470
docs/build-system/core/build-systems-overview.md
Normal file
470
docs/build-system/core/build-systems-overview.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# TimeSafari Build Systems Overview
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-07-11
|
||||
**Status**: ✅ **COMPLETE** - All build systems documented and integrated
|
||||
|
||||
## Overview
|
||||
|
||||
TimeSafari supports multiple platforms and build targets through a unified build system architecture. This document provides a comprehensive overview of all build systems, their purposes, and how they work together.
|
||||
|
||||
## Build System Architecture
|
||||
|
||||
### Platform Support Matrix
|
||||
|
||||
| Platform | Build Script | Development | Testing | Production | Package Types |
|
||||
|----------|--------------|-------------|---------|------------|---------------|
|
||||
| **Web** | `build-web.sh` | ✅ Dev Server | ✅ Test Build | ✅ Prod Build | Docker Images |
|
||||
| **Android** | `build-android.sh` | ✅ Debug APK | ✅ Test APK | ✅ Release APK/AAB | APK, AAB |
|
||||
| **iOS** | `build-ios.sh` | ✅ Debug App | ✅ Test App | ✅ Release App | IPA |
|
||||
| **Electron** | `build-electron.sh` | ✅ Dev App | ✅ Test App | ✅ Prod App | AppImage, DEB, DMG, EXE |
|
||||
|
||||
### Build Script Locations
|
||||
|
||||
```bash
|
||||
scripts/
|
||||
├── build-web.sh # Web/PWA builds
|
||||
├── build-android.sh # Android mobile builds
|
||||
├── build-ios.sh # iOS mobile builds (future)
|
||||
├── build-electron.sh # Desktop builds
|
||||
└── common.sh # Shared build utilities
|
||||
```
|
||||
|
||||
## Unified Build Pattern
|
||||
|
||||
All build scripts follow a consistent pattern:
|
||||
|
||||
### 1. **Environment Setup**
|
||||
```bash
|
||||
# Set platform-specific environment variables
|
||||
VITE_PLATFORM=<platform>
|
||||
PWA: automatically enabled for web platforms
|
||||
VITE_GIT_HASH=<git-commit-hash>
|
||||
```
|
||||
|
||||
### 2. **Argument Parsing**
|
||||
```bash
|
||||
# Consistent command-line interface
|
||||
./scripts/build-<platform>.sh [--dev|--test|--prod] [options]
|
||||
```
|
||||
|
||||
### 3. **Build Process**
|
||||
```bash
|
||||
# Standard build flow
|
||||
1. Validate environment
|
||||
2. Clean build artifacts
|
||||
3. Build web assets (Vite)
|
||||
4. Platform-specific build
|
||||
5. Generate assets
|
||||
6. Create packages (if requested)
|
||||
```
|
||||
|
||||
### 4. **Error Handling**
|
||||
```bash
|
||||
# Consistent exit codes
|
||||
1: Cleanup failed
|
||||
2: Web build failed
|
||||
3: Platform build failed
|
||||
4: Asset generation failed
|
||||
5: Package creation failed
|
||||
```
|
||||
|
||||
## Web Build System
|
||||
|
||||
### Purpose
|
||||
Builds the web application for browser and PWA deployment.
|
||||
|
||||
### Key Features
|
||||
- **Development Server**: Hot reload with Vite
|
||||
- **PWA Support**: Service workers and manifest generation
|
||||
- **Docker Integration**: Containerized deployment
|
||||
- **Environment Modes**: Development, test, production
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development (starts dev server)
|
||||
npm run build:web:dev
|
||||
|
||||
# Production build
|
||||
npm run build:web:prod
|
||||
|
||||
# Docker deployment
|
||||
npm run build:web:docker:prod
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Development**: Vite dev server at http://localhost:8080
|
||||
- **Production**: Static files in `dist/` directory
|
||||
- **Docker**: Containerized application image
|
||||
|
||||
**Documentation**: [Web Build Scripts Guide](build-web-script-integration.md)
|
||||
|
||||
## Android Build System
|
||||
|
||||
### Purpose
|
||||
Builds Android mobile applications using Capacitor and Gradle.
|
||||
|
||||
### Key Features
|
||||
- **Capacitor Integration**: Web-to-native bridge
|
||||
- **Gradle Builds**: APK and AAB generation
|
||||
- **Asset Generation**: Icons and splash screens
|
||||
- **Device Deployment**: Direct APK installation
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development build
|
||||
npm run build:android:dev
|
||||
|
||||
# Production APK
|
||||
npm run build:android:prod
|
||||
|
||||
# Deploy to device
|
||||
npm run build:android:deploy
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Debug APK**: `android/app/build/outputs/apk/debug/app-debug.apk`
|
||||
- **Release APK**: `android/app/build/outputs/apk/release/app-release.apk`
|
||||
- **AAB Bundle**: `android/app/build/outputs/bundle/release/app-release.aab`
|
||||
|
||||
### Device Deployment
|
||||
```bash
|
||||
# Automatic deployment to connected device
|
||||
npm run build:android:deploy
|
||||
|
||||
# Manual deployment
|
||||
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
|
||||
```
|
||||
|
||||
**Documentation**: [Android Build Scripts Guide](android-build-scripts.md)
|
||||
|
||||
## iOS Build System
|
||||
|
||||
### Purpose
|
||||
Builds iOS mobile applications using Capacitor and Xcode.
|
||||
|
||||
### Key Features
|
||||
- **Capacitor Integration**: Web-to-native bridge
|
||||
- **Xcode Integration**: Native iOS builds
|
||||
- **Asset Generation**: Icons and splash screens
|
||||
- **Simulator Support**: iOS simulator testing
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development build
|
||||
npm run build:ios:dev
|
||||
|
||||
# Production build
|
||||
npm run build:ios:prod
|
||||
|
||||
# Open Xcode
|
||||
npm run build:ios:studio
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Debug App**: `ios/App/build/Debug-iphonesimulator/App.app`
|
||||
- **Release App**: `ios/App/build/Release-iphoneos/App.app`
|
||||
- **IPA Package**: `ios/App/build/Release-iphoneos/App.ipa`
|
||||
|
||||
**Documentation**: [iOS Build Scripts Guide](ios-build-scripts.md) *(Future)*
|
||||
|
||||
## Electron Build System
|
||||
|
||||
### Purpose
|
||||
Builds desktop applications for Windows, macOS, and Linux.
|
||||
|
||||
### Key Features
|
||||
- **Cross-Platform**: Windows, macOS, Linux support
|
||||
- **Package Formats**: AppImage, DEB, DMG, EXE
|
||||
- **Development Mode**: Direct app execution
|
||||
- **Single Instance**: Prevents multiple app instances
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Development (runs app directly)
|
||||
npm run build:electron:dev
|
||||
|
||||
# Production AppImage
|
||||
npm run build:electron:appimage:prod
|
||||
|
||||
# Production DMG
|
||||
npm run build:electron:dmg:prod
|
||||
```
|
||||
|
||||
### Output
|
||||
- **Development**: App runs directly (no files created)
|
||||
- **Packages**: Executables in `electron/dist/` directory
|
||||
- **AppImage**: `TimeSafari-1.0.3-beta.AppImage`
|
||||
- **DEB**: `TimeSafari_1.0.3-beta_amd64.deb`
|
||||
- **DMG**: `TimeSafari-1.0.3-beta.dmg`
|
||||
- **EXE**: `TimeSafari Setup 1.0.3-beta.exe`
|
||||
|
||||
**Documentation**: [Electron Build Scripts Guide](electron-build-scripts.md)
|
||||
|
||||
## Environment Management
|
||||
|
||||
### Environment Variables
|
||||
|
||||
All build systems use consistent environment variable patterns:
|
||||
|
||||
```bash
|
||||
# Platform identification
|
||||
VITE_PLATFORM=web|capacitor|electron
|
||||
|
||||
# PWA configuration
|
||||
PWA: automatically enabled for web platforms
|
||||
|
||||
# Build information
|
||||
VITE_GIT_HASH=<git-commit-hash>
|
||||
DEBUG_MIGRATIONS=0|1
|
||||
```
|
||||
|
||||
### Environment Files
|
||||
|
||||
```bash
|
||||
.env.development # Development environment
|
||||
.env.test # Testing environment
|
||||
.env.production # Production environment
|
||||
```
|
||||
|
||||
### Mode-Specific Configuration
|
||||
|
||||
Each build mode loads appropriate environment configuration:
|
||||
|
||||
- **Development**: Local development settings
|
||||
- **Test**: Testing environment with test APIs
|
||||
- **Production**: Production environment with live APIs
|
||||
|
||||
## Package.json Integration
|
||||
|
||||
### Script Organization
|
||||
|
||||
All build scripts are integrated into `package.json` with consistent naming:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// Web builds
|
||||
"build:web": "./scripts/build-web.sh",
|
||||
"build:web:dev": "./scripts/build-web.sh --dev",
|
||||
"build:web:test": "./scripts/build-web.sh --test",
|
||||
"build:web:prod": "./scripts/build-web.sh --prod",
|
||||
|
||||
// Android builds
|
||||
"build:android": "./scripts/build-android.sh",
|
||||
"build:android:dev": "./scripts/build-android.sh --dev",
|
||||
"build:android:test": "./scripts/build-android.sh --test",
|
||||
"build:android:prod": "./scripts/build-android.sh --prod",
|
||||
|
||||
// iOS builds
|
||||
"build:ios": "./scripts/build-ios.sh",
|
||||
"build:ios:dev": "./scripts/build-ios.sh --dev",
|
||||
"build:ios:test": "./scripts/build-ios.sh --test",
|
||||
"build:ios:prod": "./scripts/build-ios.sh --prod",
|
||||
|
||||
// Electron builds
|
||||
"build:electron:dev": "./scripts/build-electron.sh --dev",
|
||||
"build:electron:test": "./scripts/build-electron.sh --test",
|
||||
"build:electron:prod": "./scripts/build-electron.sh --prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Legacy Compatibility
|
||||
|
||||
Legacy scripts are maintained as aliases for backward compatibility:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// Legacy Android scripts (aliases)
|
||||
"build:capacitor:android": "npm run build:android",
|
||||
"build:capacitor:android:dev": "npm run build:android:dev",
|
||||
"build:capacitor:android:test": "npm run build:android:test",
|
||||
"build:capacitor:android:prod": "npm run build:android:prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Build Artifacts
|
||||
|
||||
### Common Artifacts
|
||||
|
||||
All build systems generate consistent artifacts:
|
||||
|
||||
```bash
|
||||
dist/ # Web build output
|
||||
├── index.html # Main HTML file
|
||||
├── assets/ # Compiled assets
|
||||
├── manifest.webmanifest # PWA manifest
|
||||
└── sw.js # Service worker
|
||||
|
||||
android/app/build/ # Android build output
|
||||
├── outputs/apk/debug/ # Debug APKs
|
||||
├── outputs/apk/release/ # Release APKs
|
||||
└── outputs/bundle/release/ # AAB bundles
|
||||
|
||||
ios/App/build/ # iOS build output
|
||||
├── Debug-iphonesimulator/ # Debug builds
|
||||
└── Release-iphoneos/ # Release builds
|
||||
|
||||
electron/dist/ # Electron packages
|
||||
├── *.AppImage # Linux AppImages
|
||||
├── *.deb # Linux DEB packages
|
||||
├── *.dmg # macOS DMG packages
|
||||
└── *.exe # Windows installers
|
||||
```
|
||||
|
||||
### Asset Generation
|
||||
|
||||
All platforms generate platform-specific assets:
|
||||
|
||||
```bash
|
||||
# Icons and splash screens
|
||||
npx capacitor-assets generate --android
|
||||
npx capacitor-assets generate --ios
|
||||
|
||||
# PWA assets
|
||||
npx vite build --config vite.config.web.mts
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily Development
|
||||
|
||||
```bash
|
||||
# Web development
|
||||
npm run build:web:dev # Starts dev server
|
||||
|
||||
# Android development
|
||||
npm run build:android:dev # Builds debug APK
|
||||
npm run build:android:deploy # Deploy to device
|
||||
|
||||
# Electron development
|
||||
npm run build:electron:dev # Runs app directly
|
||||
```
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
```bash
|
||||
# Test all platforms
|
||||
npm run build:web:test
|
||||
npm run build:android:test
|
||||
npm run build:ios:test
|
||||
npm run build:electron:test
|
||||
```
|
||||
|
||||
### Production Workflow
|
||||
|
||||
```bash
|
||||
# Build all platforms for production
|
||||
npm run build:web:prod
|
||||
npm run build:android:prod
|
||||
npm run build:ios:prod
|
||||
npm run build:electron:prod
|
||||
|
||||
# Create distribution packages
|
||||
npm run build:electron:appimage:prod
|
||||
npm run build:electron:dmg:prod
|
||||
npm run build:electron:deb:prod
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Build Failures
|
||||
```bash
|
||||
# Clean all build artifacts
|
||||
npm run clean:all
|
||||
|
||||
# Rebuild from scratch
|
||||
npm run build:<platform>:dev
|
||||
```
|
||||
|
||||
#### Device Connection Issues
|
||||
```bash
|
||||
# Check Android device connection
|
||||
adb devices
|
||||
|
||||
# Check iOS device connection
|
||||
xcrun devicectl list devices
|
||||
```
|
||||
|
||||
#### Environment Issues
|
||||
```bash
|
||||
# Verify environment variables
|
||||
echo $VITE_PLATFORM
|
||||
echo "PWA: automatically enabled for web platforms"
|
||||
|
||||
# Check environment files
|
||||
ls -la .env*
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose logging for all build scripts:
|
||||
|
||||
```bash
|
||||
# Verbose mode
|
||||
./scripts/build-<platform>.sh --verbose
|
||||
|
||||
# Debug environment
|
||||
DEBUG_MIGRATIONS=1 npm run build:<platform>:dev
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
### Build Times (Typical)
|
||||
|
||||
| Platform | Development | Production | Package |
|
||||
|----------|-------------|------------|---------|
|
||||
| **Web** | 350ms | 8s | 12s |
|
||||
| **Android** | 45s | 60s | 75s |
|
||||
| **iOS** | 60s | 90s | 120s |
|
||||
| **Electron** | 15s | 25s | 45s |
|
||||
|
||||
### Optimization Features
|
||||
|
||||
- **Incremental Builds**: Only rebuild changed files
|
||||
- **Parallel Processing**: Multi-core build optimization
|
||||
- **Caching**: Build artifact caching
|
||||
- **Asset Optimization**: Image and code minification
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Build Security
|
||||
|
||||
- **Environment Isolation**: Separate dev/test/prod environments
|
||||
- **Secret Management**: Secure handling of API keys
|
||||
- **Code Signing**: Digital signatures for packages
|
||||
- **Dependency Scanning**: Regular security audits
|
||||
|
||||
### Distribution Security
|
||||
|
||||
- **Package Verification**: Checksum validation
|
||||
- **Code Signing**: Digital certificates for packages
|
||||
- **Update Security**: Secure update mechanisms
|
||||
- **Sandboxing**: Platform-specific security isolation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
|
||||
- **CI/CD Integration**: Automated build pipelines
|
||||
- **Cross-Platform Testing**: Unified test framework
|
||||
- **Performance Monitoring**: Build performance tracking
|
||||
- **Asset Optimization**: Advanced image and code optimization
|
||||
|
||||
### Platform Expansion
|
||||
|
||||
- **Windows Store**: Microsoft Store packages
|
||||
- **Mac App Store**: App Store distribution
|
||||
- **Google Play**: Play Store optimization
|
||||
- **App Store**: iOS App Store distribution
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-07-11
|
||||
**Version**: 1.0.3-beta
|
||||
**Status**: Production Ready
|
||||
722
docs/build-system/core/build-troubleshooting.md
Normal file
722
docs/build-system/core/build-troubleshooting.md
Normal file
@@ -0,0 +1,722 @@
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check device connection
|
||||
adb devices
|
||||
|
||||
# Enable USB debugging
|
||||
# Settings > Developer options > USB debugging
|
||||
|
||||
# Install ADB drivers (Windows)
|
||||
# Download from Google USB drivers
|
||||
```
|
||||
|
||||
#### Device Unauthorized
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check lock file
|
||||
ls -la ~/.timesafari-lock
|
||||
|
||||
# Remove lock file manually
|
||||
rm -f ~/.timesafari-lock
|
||||
|
||||
# Restart app
|
||||
npm run build:electron:dev
|
||||
```
|
||||
|
||||
#### Database Issues
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check AppImage creation
|
||||
file electron/dist/*.AppImage
|
||||
|
||||
# Make executable
|
||||
chmod +x electron/dist/*.AppImage
|
||||
|
||||
# Test AppImage
|
||||
./electron/dist/*.AppImage
|
||||
```
|
||||
|
||||
##### macOS DMG Issues
|
||||
```bash
|
||||
# Check DMG creation
|
||||
file electron/dist/*.dmg
|
||||
|
||||
# Mount DMG
|
||||
hdiutil attach electron/dist/*.dmg
|
||||
|
||||
# Check contents
|
||||
ls -la /Volumes/TimeSafari/
|
||||
```
|
||||
|
||||
##### Windows EXE Issues
|
||||
```bash
|
||||
# Check EXE creation
|
||||
file electron/dist/*.exe
|
||||
|
||||
# Test installer
|
||||
# Run the EXE file
|
||||
# Check installation directory
|
||||
```
|
||||
|
||||
## iOS Build Issues (Future)
|
||||
|
||||
### Xcode Issues
|
||||
```bash
|
||||
# Check Xcode installation
|
||||
xcode-select --print-path
|
||||
|
||||
# Install command line tools
|
||||
xcode-select --install
|
||||
|
||||
# Accept Xcode license
|
||||
sudo xcodebuild -license accept
|
||||
```
|
||||
|
||||
### Simulator Issues
|
||||
```bash
|
||||
# List available simulators
|
||||
xcrun simctl list devices
|
||||
|
||||
# Boot simulator
|
||||
xcrun simctl boot "iPhone 15 Pro"
|
||||
|
||||
# Reset simulator
|
||||
xcrun simctl erase all
|
||||
```
|
||||
|
||||
### Code Signing Issues
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check package.json
|
||||
cat package.json | grep -A 10 "dependencies"
|
||||
|
||||
# Install missing dependencies
|
||||
npm install
|
||||
|
||||
# Check for peer dependencies
|
||||
npm ls
|
||||
```
|
||||
|
||||
#### Version Conflicts
|
||||
```bash
|
||||
# Check for conflicts
|
||||
npm ls
|
||||
|
||||
# Update dependencies
|
||||
npm update
|
||||
|
||||
# Force resolution
|
||||
npm install --force
|
||||
```
|
||||
|
||||
#### Platform-Specific Dependencies
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Web builds
|
||||
./scripts/build-web.sh --verbose
|
||||
|
||||
# Android builds
|
||||
./scripts/build-android.sh --verbose
|
||||
|
||||
# Electron builds
|
||||
./scripts/build-electron.sh --verbose
|
||||
```
|
||||
|
||||
#### Debug Environment
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Open DevTools
|
||||
# Console tab for JavaScript errors
|
||||
# Network tab for API issues
|
||||
# Application tab for storage issues
|
||||
```
|
||||
|
||||
##### Android
|
||||
```bash
|
||||
# View Android logs
|
||||
adb logcat | grep -i timesafari
|
||||
|
||||
# Filter by app
|
||||
adb logcat | grep -i "app.timesafari.app"
|
||||
```
|
||||
|
||||
##### Electron
|
||||
```bash
|
||||
# View Electron logs
|
||||
# Check console output
|
||||
# Check DevTools console
|
||||
# Check main process logs
|
||||
```
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### Web Build Errors
|
||||
|
||||
#### "Module not found"
|
||||
```bash
|
||||
# Check import paths
|
||||
# Verify file exists
|
||||
# Check case sensitivity
|
||||
# Update import statements
|
||||
```
|
||||
|
||||
#### "Port already in use"
|
||||
```bash
|
||||
# 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"
|
||||
```bash
|
||||
# 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"
|
||||
```bash
|
||||
# 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"
|
||||
```bash
|
||||
# Remove lock file
|
||||
rm -f ~/.timesafari-lock
|
||||
|
||||
# Kill existing processes
|
||||
pkill -f "TimeSafari"
|
||||
|
||||
# Restart app
|
||||
npm run build:electron:dev
|
||||
```
|
||||
|
||||
#### "Code signing failed"
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Use consistent environments
|
||||
# Separate dev/test/prod configurations
|
||||
# Version control environment files
|
||||
# Document environment requirements
|
||||
```
|
||||
|
||||
#### Testing
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Track build times
|
||||
# Monitor build success rates
|
||||
# Check for performance regressions
|
||||
# Monitor bundle sizes
|
||||
```
|
||||
|
||||
#### Runtime Monitoring
|
||||
```bash
|
||||
# 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
|
||||
363
docs/build-system/core/build-web-script-integration.md
Normal file
363
docs/build-system/core/build-web-script-integration.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# Build Web Script Integration
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-07-11
|
||||
**Status**: ✅ **COMPLETE** - Successfully implemented and tested
|
||||
|
||||
## Overview
|
||||
|
||||
The `build-web.sh` script has been successfully integrated into the TimeSafari build system, providing a unified approach to web builds that eliminates the need for multiple commands with flags in npm scripts.
|
||||
|
||||
## Problem Solved
|
||||
|
||||
### Previous Issue: Multiple Commands with Flags
|
||||
|
||||
The original package.json scripts had complex command chains that made debugging and maintenance difficult:
|
||||
|
||||
```json
|
||||
// OLD PATTERN - Multiple commands with flags
|
||||
"build:web:test": "npm run build:web:build -- --mode test",
|
||||
"build:web:prod": "npm run build:web:build -- --mode production",
|
||||
"build:web:docker:test": "npm run build:web:docker -- --mode test",
|
||||
"build:web:docker:prod": "npm run build:web:docker -- --mode production"
|
||||
```
|
||||
|
||||
### New Solution: Single Script with Arguments
|
||||
|
||||
The new approach uses a single shell script that handles all build modes and options:
|
||||
|
||||
```json
|
||||
// NEW PATTERN - Single script calls
|
||||
"build:web": "./scripts/build-web.sh",
|
||||
"build:web:dev": "./scripts/build-web.sh --dev",
|
||||
"build:web:test": "./scripts/build-web.sh --test",
|
||||
"build:web:prod": "./scripts/build-web.sh --prod",
|
||||
"build:web:docker": "./scripts/build-web.sh --docker",
|
||||
"build:web:docker:test": "./scripts/build-web.sh --docker:test",
|
||||
"build:web:docker:prod": "./scripts/build-web.sh --docker:prod",
|
||||
"build:web:serve": "./scripts/build-web.sh --serve"
|
||||
```
|
||||
|
||||
## Script Architecture
|
||||
|
||||
### Design Principles
|
||||
|
||||
1. **Single Responsibility**: Each npm script calls exactly one command
|
||||
2. **Argument Parsing**: All complexity handled within the shell script
|
||||
3. **Consistent Interface**: Follows the same pattern as other build scripts
|
||||
4. **Environment Management**: Proper environment variable handling
|
||||
5. **Error Handling**: Comprehensive error checking and reporting
|
||||
6. **Development-First**: Development mode starts dev server instead of building
|
||||
|
||||
### Script Structure
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-web.sh
|
||||
# Author: Matthew Raymer
|
||||
# Description: Web build script for TimeSafari application
|
||||
|
||||
# Exit on any error
|
||||
set -e
|
||||
|
||||
# Source common utilities
|
||||
source "$(dirname "$0")/common.sh"
|
||||
|
||||
# Parse arguments and set build mode
|
||||
parse_web_args "$@"
|
||||
|
||||
# Validate environment
|
||||
validate_web_environment
|
||||
|
||||
# Setup environment
|
||||
setup_build_env "web"
|
||||
setup_web_environment
|
||||
|
||||
# Execute build steps
|
||||
clean_build_artifacts "dist"
|
||||
execute_vite_build "$BUILD_MODE"
|
||||
|
||||
# Optional steps
|
||||
if [ "$DOCKER_BUILD" = true ]; then
|
||||
execute_docker_build "$BUILD_MODE"
|
||||
fi
|
||||
|
||||
if [ "$SERVE_BUILD" = true ]; then
|
||||
serve_build
|
||||
fi
|
||||
```
|
||||
|
||||
## Build Modes Supported
|
||||
|
||||
### Development Mode (Default)
|
||||
```bash
|
||||
./scripts/build-web.sh
|
||||
./scripts/build-web.sh --dev
|
||||
```
|
||||
- Starts Vite development server with hot reload
|
||||
- No build step - runs development server directly
|
||||
- Fast startup with live reload capabilities
|
||||
- Available at http://localhost:8080
|
||||
- **Source maps enabled** for debugging
|
||||
- **PWA enabled** for development testing
|
||||
|
||||
### Test Mode
|
||||
```bash
|
||||
./scripts/build-web.sh --test
|
||||
```
|
||||
- Test environment configuration
|
||||
- Minimal minification
|
||||
- Source maps enabled
|
||||
- Uses `.env.test` file
|
||||
- **PWA enabled** for testing
|
||||
|
||||
### Production Mode
|
||||
```bash
|
||||
./scripts/build-web.sh --prod
|
||||
```
|
||||
- Full production optimizations
|
||||
- Maximum minification
|
||||
- Source maps disabled
|
||||
- Uses `.env.production` file
|
||||
- **PWA enabled** with full caching strategies
|
||||
|
||||
## Docker Integration
|
||||
|
||||
### Docker Build Options
|
||||
```bash
|
||||
# Development + Docker
|
||||
./scripts/build-web.sh --docker
|
||||
|
||||
# Test + Docker
|
||||
./scripts/build-web.sh --docker:test
|
||||
|
||||
# Production + Docker
|
||||
./scripts/build-web.sh --docker:prod
|
||||
```
|
||||
|
||||
### Docker Features
|
||||
- Automatic image tagging (`timesafari-web:mode`)
|
||||
- Build argument passing
|
||||
- Environment-specific configurations
|
||||
- Consistent image naming
|
||||
|
||||
## Local Development
|
||||
|
||||
### Development Server
|
||||
```bash
|
||||
./scripts/build-web.sh
|
||||
./scripts/build-web.sh --dev
|
||||
```
|
||||
- Starts Vite development server with hot reload
|
||||
- No build step required
|
||||
- Fast startup (~350ms)
|
||||
- Available at http://localhost:8080
|
||||
- Supports live reload and HMR
|
||||
- **Source maps enabled** for debugging
|
||||
|
||||
### Serve Build Locally
|
||||
```bash
|
||||
./scripts/build-web.sh --serve
|
||||
```
|
||||
- Builds the application first
|
||||
- Starts a local HTTP server to serve the built files
|
||||
- Supports Python HTTP server or npx serve
|
||||
- Runs on port 8080
|
||||
|
||||
## PWA Configuration
|
||||
|
||||
### PWA Best Practices Implementation
|
||||
|
||||
The TimeSafari web build follows PWA best practices by enabling PWA functionality across all environments:
|
||||
|
||||
#### ✅ **Development Mode**
|
||||
- PWA enabled for development testing
|
||||
- Service worker registration active
|
||||
- Manifest generation enabled
|
||||
- Hot reload compatible
|
||||
|
||||
#### ✅ **Test Mode**
|
||||
- PWA enabled for QA testing
|
||||
- Service worker registration active
|
||||
- Manifest generation enabled
|
||||
- Full PWA feature testing
|
||||
|
||||
#### ✅ **Production Mode**
|
||||
- PWA enabled with full caching strategies
|
||||
- Service worker registration active
|
||||
- Manifest generation enabled
|
||||
- Runtime caching for API calls
|
||||
- Optimized for production performance
|
||||
|
||||
### PWA Features Generated
|
||||
- `manifest.webmanifest` - PWA manifest with app metadata
|
||||
- `sw.js` - Service worker for offline functionality
|
||||
- `workbox-*.js` - Workbox library for caching strategies
|
||||
- Share target support for image sharing
|
||||
- Offline-first architecture
|
||||
|
||||
### Visual Confirmations of PWA Installation
|
||||
|
||||
#### ✅ **Automatic Browser Prompts**
|
||||
- **Chrome**: Install banner in address bar with install button
|
||||
- **Safari**: "Add to Home Screen" prompt
|
||||
- **Edge**: Install button in toolbar
|
||||
- **Firefox**: Install button in address bar
|
||||
|
||||
#### ✅ **Custom Install Prompt**
|
||||
- **PWAInstallPrompt Component**: Shows when PWA can be installed
|
||||
- **Install Button**: Prominent blue "Install" button
|
||||
- **Dismiss Options**: "Later" button and close button
|
||||
- **Success Notification**: Confirms successful installation
|
||||
|
||||
#### ✅ **Post-Installation Indicators**
|
||||
- **App Icon**: Appears on device home screen/start menu
|
||||
- **Standalone Window**: Opens without browser UI
|
||||
- **Native Experience**: Full-screen app-like behavior
|
||||
- **Offline Capability**: Works without internet connection
|
||||
|
||||
#### ✅ **Installation Status Detection**
|
||||
- **Display Mode Detection**: Checks for standalone/fullscreen modes
|
||||
- **Service Worker Status**: Monitors service worker registration
|
||||
- **Install Event Handling**: Listens for successful installation
|
||||
- **Environment Awareness**: Only shows when PWA is enabled
|
||||
|
||||
### Environment Variables Set
|
||||
- `VITE_PLATFORM=web`
|
||||
- `VITE_PWA_ENABLED=true`
|
||||
- `VITE_DISABLE_PWA=false`
|
||||
- `NODE_ENV` (based on build mode)
|
||||
- `VITE_GIT_HASH` (from git)
|
||||
|
||||
## Environment Management
|
||||
|
||||
### Environment File Loading
|
||||
The script automatically loads environment files based on build mode:
|
||||
|
||||
1. `.env.{mode}` (e.g., `.env.test`, `.env.production`)
|
||||
2. `.env` (fallback)
|
||||
|
||||
## Integration with Existing System
|
||||
|
||||
### Common Utilities
|
||||
The script leverages the existing `common.sh` utilities:
|
||||
- `log_info`, `log_success`, `log_error` - Consistent logging
|
||||
- `measure_time` - Performance tracking
|
||||
- `safe_execute` - Error handling
|
||||
- `setup_build_env` - Environment setup
|
||||
- `clean_build_artifacts` - Cleanup operations
|
||||
|
||||
### Consistent Patterns
|
||||
Follows the same patterns as other build scripts:
|
||||
- `build-electron.sh` - Electron builds
|
||||
- `build-android.sh` - Android builds
|
||||
- `build-ios.sh` - iOS builds
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Builds
|
||||
```bash
|
||||
# Development server (starts dev server)
|
||||
npm run build:web
|
||||
|
||||
# Test environment build
|
||||
npm run build:web:test
|
||||
|
||||
# Production build
|
||||
npm run build:web:prod
|
||||
```
|
||||
|
||||
### Docker Builds
|
||||
```bash
|
||||
# Development + Docker
|
||||
npm run build:web:docker
|
||||
|
||||
# Test + Docker
|
||||
npm run build:web:docker:test
|
||||
|
||||
# Production + Docker
|
||||
npm run build:web:docker:prod
|
||||
```
|
||||
|
||||
### Direct Script Usage
|
||||
```bash
|
||||
# Show help
|
||||
./scripts/build-web.sh --help
|
||||
|
||||
# Show environment variables
|
||||
./scripts/build-web.sh --env
|
||||
|
||||
# Verbose logging
|
||||
./scripts/build-web.sh --test --verbose
|
||||
```
|
||||
|
||||
## Benefits Achieved
|
||||
|
||||
### 1. Simplified NPM Scripts
|
||||
- No more complex command chains
|
||||
- Single command per script
|
||||
- Easy to understand and maintain
|
||||
|
||||
### 2. Better Error Handling
|
||||
- Comprehensive error checking
|
||||
- Clear error messages
|
||||
- Proper exit codes
|
||||
|
||||
### 3. Consistent Logging
|
||||
- Structured log output
|
||||
- Performance timing
|
||||
- Build step tracking
|
||||
|
||||
### 4. Environment Management
|
||||
- Automatic environment file loading
|
||||
- Platform-specific configurations
|
||||
- Git hash integration
|
||||
|
||||
### 5. Docker Integration
|
||||
- Seamless Docker builds
|
||||
- Environment-aware containerization
|
||||
- Consistent image tagging
|
||||
|
||||
## Testing Results
|
||||
|
||||
### Build Performance
|
||||
- **Development Mode**: ~350ms startup time (dev server)
|
||||
- **Test Mode**: ~11 seconds build time
|
||||
- **Production Mode**: ~12 seconds build time
|
||||
|
||||
### Environment Loading
|
||||
- Successfully loads `.env.test` for test builds
|
||||
- Properly sets `NODE_ENV` based on build mode
|
||||
- Correctly applies Vite mode configurations
|
||||
|
||||
### Docker Integration
|
||||
- Docker builds complete successfully
|
||||
- Images tagged correctly (`timesafari-web:test`, etc.)
|
||||
- Build arguments passed properly
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Improvements
|
||||
1. **Parallel Builds**: Support for parallel asset processing
|
||||
2. **Build Caching**: Implement build caching for faster rebuilds
|
||||
3. **Custom Ports**: Allow custom port specification for serve mode
|
||||
4. **Build Profiles**: Support for custom build profiles
|
||||
5. **Watch Mode**: Add development watch mode support
|
||||
|
||||
### Integration Opportunities
|
||||
1. **CI/CD Integration**: Easy integration with GitHub Actions
|
||||
2. **Multi-Platform Builds**: Extend to support other platforms
|
||||
3. **Build Analytics**: Add build performance analytics
|
||||
4. **Dependency Checking**: Automatic dependency validation
|
||||
|
||||
## Conclusion
|
||||
|
||||
The `build-web.sh` script successfully addresses the requirement to prevent scripts from having multiple commands with flags while providing a robust, maintainable, and feature-rich build system for the TimeSafari web application.
|
||||
|
||||
The implementation follows established patterns in the codebase, leverages existing utilities, and provides a consistent developer experience across all build modes and platforms.
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ **COMPLETE** - Ready for production use
|
||||
**Test Coverage**: 100% - All build modes tested and working
|
||||
**Documentation**: Complete with usage examples and integration guide
|
||||
594
docs/build-system/core/electron-build-patterns.md
Normal file
594
docs/build-system/core/electron-build-patterns.md
Normal file
@@ -0,0 +1,594 @@
|
||||
# Electron Build Patterns
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-01-27
|
||||
**Status**: 🎯 **ACTIVE** - Current Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
TimeSafari's Electron build system provides comprehensive packaging and
|
||||
distribution capabilities across Windows, macOS, and Linux platforms. The
|
||||
system supports multiple build modes, environment configurations, and
|
||||
package formats for different deployment scenarios.
|
||||
|
||||
## Build Architecture
|
||||
|
||||
### Multi-Stage Build Process
|
||||
|
||||
```
|
||||
1. Web Build (Vite) → 2. Capacitor Sync → 3. TypeScript Compile → 4. Package
|
||||
```
|
||||
|
||||
**Stage 1: Web Build**
|
||||
- Vite builds web assets with Electron-specific configuration
|
||||
- Environment variables loaded based on build mode
|
||||
- Assets optimized for desktop application
|
||||
|
||||
**Stage 2: Capacitor Sync**
|
||||
- Copies web assets to Electron app directory
|
||||
- Syncs Capacitor configuration and plugins
|
||||
- Prepares native module bindings
|
||||
|
||||
**Stage 3: TypeScript Compile**
|
||||
- Compiles Electron main process TypeScript
|
||||
- Rebuilds native modules for target platform
|
||||
- Generates production-ready JavaScript
|
||||
|
||||
**Stage 4: Package Creation**
|
||||
- Creates platform-specific installers
|
||||
- Generates distribution packages
|
||||
- Signs applications (when configured)
|
||||
|
||||
## Build Modes
|
||||
|
||||
### Development Mode (--mode development)
|
||||
|
||||
**Purpose**: Local development and testing
|
||||
**Configuration**: Development environment variables
|
||||
**Output**: Unpacked application for testing
|
||||
|
||||
```bash
|
||||
# Development build (runs app)
|
||||
npm run build:electron:dev
|
||||
|
||||
# Development build with explicit mode
|
||||
npm run build:electron -- --mode development
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Hot reload enabled
|
||||
- Debug tools available
|
||||
- Development logging
|
||||
- Unoptimized assets
|
||||
|
||||
### Testing Mode (--mode test)
|
||||
|
||||
**Purpose**: Staging and testing environments
|
||||
**Configuration**: Test environment variables
|
||||
**Output**: Packaged application for testing
|
||||
|
||||
```bash
|
||||
# Test build
|
||||
npm run build:electron -- --mode test
|
||||
|
||||
# Test build with specific platform
|
||||
npm run build:electron:windows -- --mode test
|
||||
npm run build:electron:mac -- --mode test
|
||||
npm run build:electron:linux -- --mode test
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Test API endpoints
|
||||
- Staging configurations
|
||||
- Optimized for testing
|
||||
- Debug information available
|
||||
|
||||
### Production Mode (--mode production)
|
||||
|
||||
**Purpose**: Production deployment
|
||||
**Configuration**: Production environment variables
|
||||
**Output**: Optimized distribution packages
|
||||
|
||||
```bash
|
||||
# Production build
|
||||
npm run build:electron -- --mode production
|
||||
|
||||
# Production build with specific platform
|
||||
npm run build:electron:windows -- --mode production
|
||||
npm run build:electron:mac -- --mode production
|
||||
npm run build:electron:linux -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Production optimizations
|
||||
- Code minification
|
||||
- Security hardening
|
||||
- Performance optimizations
|
||||
|
||||
## Platform-Specific Builds
|
||||
|
||||
### Windows Builds
|
||||
|
||||
**Target Platforms**: Windows 10/11 (x64)
|
||||
**Package Formats**: NSIS installer, portable executable
|
||||
|
||||
```bash
|
||||
# Windows development build
|
||||
npm run build:electron:windows -- --mode development
|
||||
|
||||
# Windows test build
|
||||
npm run build:electron:windows -- --mode test
|
||||
|
||||
# Windows production build
|
||||
npm run build:electron:windows -- --mode production
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- NSIS installer with custom options
|
||||
- Desktop and Start Menu shortcuts
|
||||
- Elevation permissions for installation
|
||||
- Custom installation directory support
|
||||
|
||||
### macOS Builds
|
||||
|
||||
**Target Platforms**: macOS 10.15+ (x64, arm64)
|
||||
**Package Formats**: DMG installer, app bundle
|
||||
|
||||
```bash
|
||||
# macOS development build
|
||||
npm run build:electron:mac -- --mode development
|
||||
|
||||
# macOS test build
|
||||
npm run build:electron:mac -- --mode test
|
||||
|
||||
# macOS production build
|
||||
npm run build:electron:mac -- --mode production
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- Universal binary (x64 + arm64)
|
||||
- DMG installer with custom branding
|
||||
- App Store compliance (when configured)
|
||||
- Code signing support
|
||||
|
||||
### Linux Builds
|
||||
|
||||
**Target Platforms**: Ubuntu 18.04+, Debian 10+, Arch Linux
|
||||
**Package Formats**: AppImage, DEB, RPM
|
||||
|
||||
```bash
|
||||
# Linux development build
|
||||
npm run build:electron:linux -- --mode development
|
||||
|
||||
# Linux test build
|
||||
npm run build:electron:linux -- --mode test
|
||||
|
||||
# Linux production build
|
||||
npm run build:electron:linux -- --mode production
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- AppImage for universal distribution
|
||||
- DEB package for Debian-based systems
|
||||
- RPM package for Red Hat-based systems
|
||||
- Desktop integration
|
||||
|
||||
## Package-Specific Builds
|
||||
|
||||
### AppImage Package
|
||||
|
||||
**Format**: Self-contained Linux executable
|
||||
**Distribution**: Universal Linux distribution
|
||||
|
||||
```bash
|
||||
# AppImage development build
|
||||
npm run build:electron:appimage -- --mode development
|
||||
|
||||
# AppImage test build
|
||||
npm run build:electron:appimage -- --mode test
|
||||
|
||||
# AppImage production build
|
||||
npm run build:electron:appimage -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Single file distribution
|
||||
- No installation required
|
||||
- Portable across Linux distributions
|
||||
- Automatic updates support
|
||||
|
||||
### DEB Package
|
||||
|
||||
**Format**: Debian package installer
|
||||
**Distribution**: Debian-based Linux systems
|
||||
|
||||
```bash
|
||||
# DEB development build
|
||||
npm run build:electron:deb -- --mode development
|
||||
|
||||
# DEB test build
|
||||
npm run build:electron:deb -- --mode test
|
||||
|
||||
# DEB production build
|
||||
npm run build:electron:deb -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Native package management
|
||||
- Dependency resolution
|
||||
- System integration
|
||||
- Easy installation/uninstallation
|
||||
|
||||
### DMG Package
|
||||
|
||||
**Format**: macOS disk image
|
||||
**Distribution**: macOS systems
|
||||
|
||||
```bash
|
||||
# DMG development build
|
||||
npm run build:electron:dmg -- --mode development
|
||||
|
||||
# DMG test build
|
||||
npm run build:electron:dmg -- --mode test
|
||||
|
||||
# DMG production build
|
||||
npm run build:electron:dmg -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Native macOS installer
|
||||
- Custom branding and layout
|
||||
- Drag-and-drop installation
|
||||
- Code signing support
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**Development Environment**:
|
||||
```bash
|
||||
VITE_API_URL=http://localhost:3000
|
||||
VITE_DEBUG=true
|
||||
VITE_LOG_LEVEL=debug
|
||||
VITE_ENABLE_DEV_TOOLS=true
|
||||
```
|
||||
|
||||
**Testing Environment**:
|
||||
```bash
|
||||
VITE_API_URL=https://test-api.timesafari.com
|
||||
VITE_DEBUG=false
|
||||
VITE_LOG_LEVEL=info
|
||||
VITE_ENABLE_DEV_TOOLS=false
|
||||
```
|
||||
|
||||
**Production Environment**:
|
||||
```bash
|
||||
VITE_API_URL=https://api.timesafari.com
|
||||
VITE_DEBUG=false
|
||||
VITE_LOG_LEVEL=warn
|
||||
VITE_ENABLE_DEV_TOOLS=false
|
||||
```
|
||||
|
||||
### Build Configuration
|
||||
|
||||
**Vite Configuration** (`vite.config.electron.mts`):
|
||||
```typescript
|
||||
export default defineConfig(({ mode }) => {
|
||||
const env = loadEnv(mode, process.cwd(), '');
|
||||
|
||||
return {
|
||||
mode,
|
||||
build: {
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true,
|
||||
sourcemap: mode === 'development',
|
||||
minify: mode === 'production'
|
||||
},
|
||||
define: {
|
||||
__DEV__: mode === 'development',
|
||||
__TEST__: mode === 'test',
|
||||
__PROD__: mode === 'production'
|
||||
}
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
**Electron Builder Configuration** (`electron-builder.config.json`):
|
||||
```json
|
||||
{
|
||||
"appId": "app.timesafari.desktop",
|
||||
"productName": "TimeSafari",
|
||||
"directories": {
|
||||
"buildResources": "resources",
|
||||
"output": "dist"
|
||||
},
|
||||
"files": [
|
||||
"assets/**/*",
|
||||
"build/**/*",
|
||||
"capacitor.config.*",
|
||||
"app/**/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Build Scripts Reference
|
||||
|
||||
### Main Build Scripts
|
||||
|
||||
```bash
|
||||
# Development builds
|
||||
npm run build:electron:dev # Development build and run
|
||||
npm run build:electron --dev # Development build only
|
||||
|
||||
# Testing builds
|
||||
npm run build:electron:test # Test environment build
|
||||
|
||||
# Production builds
|
||||
npm run build:electron:prod # Production environment build
|
||||
```
|
||||
|
||||
### Platform-Specific Scripts
|
||||
|
||||
```bash
|
||||
# Windows builds
|
||||
npm run build:electron:windows # Windows production build
|
||||
npm run build:electron:windows:dev # Windows development build
|
||||
npm run build:electron:windows:test # Windows test build
|
||||
npm run build:electron:windows:prod # Windows production build
|
||||
|
||||
# macOS builds
|
||||
npm run build:electron:mac # macOS production build
|
||||
npm run build:electron:mac:dev # macOS development build
|
||||
npm run build:electron:mac:test # macOS test build
|
||||
npm run build:electron:mac:prod # macOS production build
|
||||
|
||||
# Linux builds
|
||||
npm run build:electron:linux # Linux production build
|
||||
npm run build:electron:linux:dev # Linux development build
|
||||
npm run build:electron:linux:test # Linux test build
|
||||
npm run build:electron:linux:prod # Linux production build
|
||||
```
|
||||
|
||||
### Package-Specific Scripts
|
||||
|
||||
```bash
|
||||
# AppImage builds
|
||||
npm run build:electron:appimage # Linux AppImage production build
|
||||
npm run build:electron:appimage:dev # AppImage development build
|
||||
npm run build:electron:appimage:test # AppImage test build
|
||||
npm run build:electron:appimage:prod # AppImage production build
|
||||
|
||||
# DEB builds
|
||||
npm run build:electron:deb # Debian package production build
|
||||
npm run build:electron:deb:dev # DEB development build
|
||||
npm run build:electron:deb:test # DEB test build
|
||||
npm run build:electron:deb:prod # DEB production build
|
||||
|
||||
# DMG builds
|
||||
npm run build:electron:dmg # macOS DMG production build
|
||||
npm run build:electron:dmg:dev # DMG development build
|
||||
npm run build:electron:dmg:test # DMG test build
|
||||
npm run build:electron:dmg:prod # DMG production build
|
||||
```
|
||||
|
||||
### Direct Script Usage
|
||||
|
||||
All npm scripts use the underlying `./scripts/build-electron.sh` script:
|
||||
|
||||
```bash
|
||||
# Direct script usage examples
|
||||
./scripts/build-electron.sh --dev # Development build
|
||||
./scripts/build-electron.sh --test # Test build
|
||||
./scripts/build-electron.sh --prod # Production build
|
||||
./scripts/build-electron.sh --prod --windows # Windows production
|
||||
./scripts/build-electron.sh --test --appimage # Linux AppImage test
|
||||
./scripts/build-electron.sh --dev --mac # macOS development
|
||||
./scripts/build-electron.sh --prod --dmg # macOS DMG production
|
||||
```
|
||||
|
||||
### Utility Scripts
|
||||
|
||||
```bash
|
||||
# Cleanup scripts
|
||||
npm run clean:electron # Clean Electron build artifacts
|
||||
|
||||
# Development scripts
|
||||
npm run electron:dev # Start development server
|
||||
npm run electron:dev-full # Full development workflow
|
||||
```
|
||||
|
||||
## Build Output Structure
|
||||
|
||||
### Development Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Build artifacts (empty in dev)
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Distribution packages
|
||||
│ ├── TimeSafari.exe # Windows executable
|
||||
│ ├── TimeSafari.dmg # macOS installer
|
||||
│ ├── TimeSafari.AppImage # Linux AppImage
|
||||
│ └── TimeSafari.deb # Debian package
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Build Issues
|
||||
|
||||
**TypeScript Compilation Errors**:
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
npm run clean:electron
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Native Module Issues**:
|
||||
```bash
|
||||
# Rebuild native modules
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Asset Copy Issues**:
|
||||
```bash
|
||||
# Verify Capacitor sync
|
||||
npx cap sync electron
|
||||
```
|
||||
|
||||
**Package Creation Failures**:
|
||||
```bash
|
||||
# Check electron-builder configuration
|
||||
# Verify platform-specific requirements
|
||||
# Check signing certificates (macOS/Windows)
|
||||
```
|
||||
|
||||
### Platform-Specific Issues
|
||||
|
||||
**Windows**:
|
||||
- Ensure Windows Build Tools installed
|
||||
- Check NSIS installation
|
||||
- Verify code signing certificates
|
||||
|
||||
**macOS**:
|
||||
- Install Xcode Command Line Tools
|
||||
- Configure code signing certificates
|
||||
- Check app notarization requirements
|
||||
|
||||
**Linux**:
|
||||
- Install required packages (rpm-tools, etc.)
|
||||
- Check AppImage dependencies
|
||||
- Verify desktop integration
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Build Performance
|
||||
|
||||
**Parallel Builds**:
|
||||
- Use concurrent TypeScript compilation
|
||||
- Optimize asset copying
|
||||
- Minimize file system operations
|
||||
|
||||
**Caching Strategies**:
|
||||
- Cache node_modules between builds
|
||||
- Cache compiled TypeScript
|
||||
- Cache web assets when unchanged
|
||||
|
||||
### Runtime Performance
|
||||
|
||||
**Application Startup**:
|
||||
- Optimize main process initialization
|
||||
- Minimize startup dependencies
|
||||
- Use lazy loading for features
|
||||
|
||||
**Memory Management**:
|
||||
- Monitor memory usage
|
||||
- Implement proper cleanup
|
||||
- Optimize asset loading
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Code Signing
|
||||
|
||||
**Windows**:
|
||||
- Authenticode code signing
|
||||
- EV certificate for SmartScreen
|
||||
- Timestamp server configuration
|
||||
|
||||
**macOS**:
|
||||
- Developer ID code signing
|
||||
- App notarization
|
||||
- Hardened runtime
|
||||
|
||||
**Linux**:
|
||||
- GPG signing for packages
|
||||
- AppImage signing
|
||||
- Package verification
|
||||
|
||||
### Security Hardening
|
||||
|
||||
**Production Builds**:
|
||||
- Disable developer tools
|
||||
- Remove debug information
|
||||
- Enable security policies
|
||||
- Implement sandboxing
|
||||
|
||||
**Update Security**:
|
||||
- Secure update channels
|
||||
- Package integrity verification
|
||||
- Rollback capabilities
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
# Example workflow for Electron builds
|
||||
- name: Build Electron
|
||||
run: |
|
||||
npm run build:electron -- --mode production
|
||||
npm run build:electron:windows -- --mode production
|
||||
npm run build:electron:mac -- --mode production
|
||||
npm run build:electron:linux -- --mode production
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
```yaml
|
||||
# Test Electron builds
|
||||
- name: Test Electron
|
||||
run: |
|
||||
npm run build:electron -- --mode test
|
||||
# Run automated tests
|
||||
```
|
||||
|
||||
### Release Management
|
||||
|
||||
```yaml
|
||||
# Create releases with assets
|
||||
- name: Create Release
|
||||
run: |
|
||||
# Upload built packages
|
||||
# Create GitHub release
|
||||
# Publish to distribution channels
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Use development mode for local testing**
|
||||
2. **Test builds in all environments**
|
||||
3. **Validate packages before distribution**
|
||||
4. **Maintain consistent versioning**
|
||||
|
||||
### Build Optimization
|
||||
|
||||
1. **Minimize build dependencies**
|
||||
2. **Use efficient asset processing**
|
||||
3. **Implement proper caching**
|
||||
4. **Optimize for target platforms**
|
||||
|
||||
### Quality Assurance
|
||||
|
||||
1. **Test on all target platforms**
|
||||
2. **Validate installation processes**
|
||||
3. **Check update mechanisms**
|
||||
4. **Verify security configurations**
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active implementation
|
||||
**Last Updated**: 2025-01-27
|
||||
**Version**: 1.0
|
||||
**Maintainer**: Matthew Raymer
|
||||
Reference in New Issue
Block a user