forked from jsnbuchanan/crowd-funder-for-time-pwa
0960d9dda3
- Change build:* naming from hyphen to colon (build:web-dev → build:web:dev) - Add missing build:web:test and build:web:prod scripts - Update build:electron:dev to include electron startup (build + start) - Remove hardcoded --mode electron to allow proper mode override - Add comprehensive mode override behavior documentation - Fix mode conflicts between hardcoded and passed --mode arguments The plan now properly supports: - Development builds with default --mode development - Testing builds with explicit --mode test override - Production builds with explicit --mode production override - Consistent naming across all platforms (web, capacitor, electron)
570 lines
18 KiB
Markdown
570 lines
18 KiB
Markdown
# 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
|
|
```
|
|
|
|
### 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
|
|
|
|
# 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 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"
|
|
"build:web:docker": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --config vite.config.web.mts",
|
|
"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",
|
|
"build:web-docker-test": "npm run build:web-docker -- --mode test",
|
|
"build:web-docker-prod": "npm run build:web-docker -- --mode production"
|
|
}
|
|
```
|
|
|
|
### 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
|
|
|
|
#### 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
|