trent_larson/crowd-funder-for-time-pwa
4
1
Fork 2
Code Issues Pull Requests 22 Releases 5 Wiki Activity

Merge branch 'master' into firebase-build-command

Browse Source
This commit is contained in:
Jose Olarte III
2026-10-13 15:41:53 -04:00
parent cbbf9d7bc0 7133c4d574
commit 59f503d90a
54 changed files with 619 additions and 9945 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BUILDING.md
+68 -228
View File
@@ -9,9 +9,9 @@ This guide explains how to build TimeSafari for different platforms using the co
```bash
# 🖥️ Web Development
npm install # setup -- and pkgx.dev `dev` command before this will set environment with npm, etc
npm run build:web:serve -- --test # Start with test endorser server
npm run dev # Start development server with hot reload with local endorser server
npm run build:web:prod # Production build
npm run build:web:serve:test # Test build served from dist/ (test endorser server)
npm run build:web # Production build into dist/
# 📱 Mobile Development
npm run build:ios # iOS build (opens Xcode)
@@ -225,30 +225,35 @@ npm install
```bash
# Local development
npm run dev # Start development server with hot reload (shortcut for `build:web:dev`)
npm run dev # Start development server with hot reload (writes nothing to dist/)
# Web builds
npm run build:web # Development build (starts dev server with hot reload)
# Web builds (each one writes dist/)
npm run build:web # Production build (same as build:web:prod)
npm run build:web:test # Test environment build (optimized for testing)
npm run build:web:prod # Production build (optimized for production)
npm run build:web:serve # Build and serve locally for production testing
# Build, then serve dist/ locally
npm run build:web:serve # Production build, then serve
npm run build:web:serve:test # Test build, then serve
# Docker builds
npm run build:web:docker # Development build with Docker containerization
npm run build:web:docker # Production build with Docker containerization
npm run build:web:docker:test # Test build with Docker containerization
npm run build:web:docker:prod # Production build with Docker containerization
```
### Local Development
Start the development server using `npm run dev` (a shortcut for `npm run build:web:dev`) or `npm run build:web` (both start the development server with hot reload).
Start the development server with hot reload using `npm run dev`. Open it at `http://localhost:8080/`, not at a wildcard address such as `http://[::]:8080/` or `http://0.0.0.0:8080/`: browsers only allow the cryptography the app needs on HTTPS, `localhost`, `127.0.0.1`, or `[::1]`, so any other plain-HTTP address shows a "Cannot Start Here" page.
### Web Build for Server
1. Run the production build using `npm run build:web:prod`
1. Run the production build using `npm run build:web` (or `npm run build:web:test` for the test server)
2. The built files will be in the `dist` directory
3. To test the production build locally, use `npm run build:web:serve` (builds then serves)
`dist/` is shared with the Android, iOS, Electron, and Capacitor builds, which overwrite it with non-web output. Run the web build immediately before deploying, and confirm that the browser console reports `Loading TimeSafari for platform: web`.
**Why Use `serve`?**
- **Production Testing**: Test your optimized production build locally before deployment
- **SPA Routing Validation**: Verify deep linking and navigation work correctly (handles routes like `/discover`, `/account`)
@@ -1603,8 +1608,7 @@ Use the commands above to check and fix code quality issues.
1. **Environment Setup**: Load platform-specific environment variables
2. **Asset Building**: Vite builds optimized web assets
3. **PWA Generation**: Service worker and manifest creation
4. **Output**: Production-ready files in `dist/` directory
3. **Output**: Production-ready files in `dist/` directory
### Electron Build Process
@@ -1856,38 +1860,21 @@ npm run build:android:assets
### Build Process Overview
TimeSafari's build system follows a multi-stage process that prepares assets,
combines scripts, and generates platform-specific outputs.
TimeSafari's build system follows a multi-stage process that prepares assets
and generates platform-specific outputs.
#### Pre-Build Preparation
##### 1. Service Worker Script Preparation
```bash
# Optional: Format third-party service worker scripts
npx prettier --write ./sw_scripts/
```
**What this does:**
- Formats cryptographic libraries (`nacl.js`, `noble-curves.js`,
`noble-hashes.js`, etc.)
- These scripts are automatically combined during the build process
- Improves readability and makes version control diffs cleaner
- **Note**: This is optional and only needed when updating third-party scripts
**2. Automatic Pre-Build Steps**
The `prebuild` script automatically runs before any build:
#### Pre-Build Script
```json
"prebuild": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src && node sw_combine.js && node scripts/copy-wasm.js"
"prebuild": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src && node scripts/copy-wasm.js"
```
**What happens automatically:**
npm runs `prebuild` only before a script named `build`. This project defines
no `build` script, so none of the `build:*` commands trigger it.
- **ESLint**: Checks and fixes code formatting in `src/`
- **Script Combination**: `sw_combine.js` combines all `sw_scripts/*.js` files
into `sw_scripts-combined.js`
**What it does when run:**
- **ESLint**: Checks code formatting in `src/`
- **WASM Copy**: `copy-wasm.js` copies SQLite WASM files to `public/wasm/`
#### Build Process Architecture
@@ -1895,11 +1882,10 @@ The `prebuild` script automatically runs before any build:
**Web Build Process:**
```text
1. Pre-Build: ESLint + Script Combination + WASM Copy
2. Environment Setup: Load .env files, set NODE_ENV
3. Vite Build: Bundle web assets with PWA support
4. Service Worker: Inject combined scripts into PWA
5. Output: Production-ready files in dist/
1. Environment Setup: Load .env files, set NODE_ENV
2. Type Check: tsc --noEmit (test and production modes)
3. Vite Build: Bundle web assets
4. Output: Production-ready files in dist/
```
**Electron Build Process:**
@@ -1922,34 +1908,6 @@ The `prebuild` script automatically runs before any build:
5. Package Creation: APK/IPA generation
```
#### Service Worker Architecture
**Script Organization:**
- `sw_scripts/` - Individual third-party scripts
- `sw_combine.js` - Combines scripts into single file
- `sw_scripts-combined.js` - Combined service worker (317KB, 10K+ lines)
- `vite.config.utils.mts` - PWA configuration using combined script
**PWA Integration:**
```typescript
// vite.config.utils.mts
pwaConfig: {
strategies: "injectManifest",
filename: "sw_scripts-combined.js", // Uses our combined script
// ... manifest configuration
}
```
**What Gets Combined:**
- `nacl.js` - NaCl cryptographic library
- `noble-curves.js` - Elliptic curve cryptography (177KB)
- `noble-hashes.js` - Cryptographic hash functions (91KB)
- `safari-notifications.js` - Safari-specific notifications
- `additional-scripts.js` - Additional service worker functionality
#### Process Environment Configuration
**Environment Files:**
@@ -2002,10 +1960,13 @@ device)
```folders
dist/
├── index.html # Main HTML file
├── assets/ # Bundled JavaScript/CSS
├── sw.js # Service worker (injected)
├── manifest.webmanifest # PWA manifest
└── wasm/ # SQLite WASM files
├── assets/ # Bundled JavaScript, CSS, and SQLite WASM
├── img/ # Static images (copied from public/)
├── models/ # Static model files (copied from public/)
├── favicon.ico
├── manifest.webmanifest # Web app manifest, incl. share_target (copied from public/)
├── robots.txt
└── sw.js # Service worker for the Web Share Target (copied from public/)
```
**Electron Build:**
@@ -2027,17 +1988,14 @@ electron/
**Manual Steps (Developer Responsibility):**
- Database migration testing
- Service worker script formatting (optional)
- Version updates and changelog
- Environment-specific builds
**Automatic Steps (Build System):**
- Code linting and formatting
- Script combination
- Type checking (test and production builds)
- Asset optimization
- Package creation
- Service worker injection
This architecture ensures consistent builds across all platforms while providing
flexibility for platform-specific optimizations and manual quality assurance steps.
@@ -2062,31 +2020,34 @@ environment setup, Vite build, and optional Docker containerization.
```bash
# Direct script usage
./scripts/build-web.sh # Development build
./scripts/build-web.sh --dev # Development build (explicit)
./scripts/build-web.sh # Production build into dist/
./scripts/build-web.sh --prod # Production build (explicit)
./scripts/build-web.sh --test # Test environment build
./scripts/build-web.sh --prod # Production environment build
./scripts/build-web.sh --docker # Build with Docker containerization
./scripts/build-web.sh --dev # Start Vite dev server (no dist/)
./scripts/build-web.sh --docker # Production build + Docker image
./scripts/build-web.sh --docker:test # Test environment + Docker
./scripts/build-web.sh --docker:prod # Production environment + Docker
./scripts/build-web.sh --serve # Build and serve locally
./scripts/build-web.sh --serve # Production build, then serve dist/
./scripts/build-web.sh --help # Show help
./scripts/build-web.sh --verbose # Enable verbose logging
# NPM Script Equivalents
npm run build:web # Development build
npm run dev # Vite dev server
npm run build:web # Production build
npm run build:web:test # Test environment build
npm run build:web:prod # Production environment build
npm run build:web:docker # Docker build
npm run build:web:docker # Production Docker build
npm run build:web:docker:test # Test Docker build
npm run build:web:docker:prod # Production Docker build
npm run build:web:serve # Production build, then serve
npm run build:web:serve:test # Test build, then serve
```
**Build Modes**:
- **Development**: Starts Vite dev server with hot reload (default)
- **Production**: Optimized for production with full minification (default)
- **Test**: Optimized for testing with minimal minification
- **Production**: Optimized for production with full minification
- **Development**: Starts Vite dev server with hot reload (`--dev` alone); with `--serve` or `--docker`, builds `dist/` in development mode
**Script Features**:
@@ -2439,9 +2400,7 @@ export async function createBuildConfig(platform: string): Promise<UserConfig> {
const appConfig = await loadAppConfig();
const isCapacitor = platform === "capacitor";
const isElectron = platform === "electron";
const isNative = isCapacitor || isElectron;
// Set platform - PWA is always enabled for web platforms
process.env.VITE_PLATFORM = platform;
return {
@@ -2457,7 +2416,6 @@ export async function createBuildConfig(platform: string): Promise<UserConfig> {
assetsDir: 'assets',
chunkSizeWarningLimit: 1000,
rollupOptions: {
external: isNative ? ['@capacitor/app'] : [],
output: {
format: 'esm',
generatedCode: { preset: 'es2015' },
@@ -2489,12 +2447,7 @@ export async function createBuildConfig(platform: string): Promise<UserConfig> {
'@jlongster/sql.js',
'absurd-sql',
// ... additional dependencies
],
exclude: isNative ? [
'register-service-worker',
'workbox-window',
// ... native exclusions
] : []
]
}
};
}
@@ -2517,98 +2470,23 @@ export async function createBuildConfig(platform: string): Promise<UserConfig> {
**File**: `vite.config.web.mts`
**Author**: Matthew Raymer
**Description**: Vite configuration for web platform with PWA support
**Description**: Vite configuration for the web platform
**Purpose**: Configures Vite for web builds with environment-specific
optimizations and PWA features.
**Purpose**: Configures Vite for web builds by delegating to the common
configuration with the `web` platform.
**Configuration Structure**:
```typescript
export default defineConfig(async () => createBuildConfig('web'));
```
**Key Features**:
- **Environment-Specific Configuration**: Different settings for dev/test/prod
- **PWA Integration**: Progressive Web App support with service worker
- **Build Optimization**: Manual chunk splitting for better caching
- **Source Maps**: Environment-specific source map configuration
- **Caching Strategies**: Production-specific API caching
**Environment Configurations**:
**Development Mode**:
```typescript
{
build: {
minify: false,
sourcemap: true,
rollupOptions: { output: { manualChunks: undefined } }
},
define: {
__DEV__: true,
__TEST__: false,
__PROD__: false
}
}
```
**Test Mode**:
```typescript
{
build: {
minify: false,
sourcemap: true,
rollupOptions: { output: { manualChunks: undefined } }
},
define: {
__DEV__: false,
__TEST__: true,
__PROD__: false
}
}
```
**Production Mode**:
```typescript
{
build: {
minify: 'terser',
sourcemap: false,
rollupOptions: {
output: {
manualChunks: {
vendor: ['vue', 'vue-router', 'pinia'],
utils: ['luxon', 'ramda', 'zod'],
crypto: ['@ethersproject/wallet', '@ethersproject/hdnode'],
sql: ['@jlongster/sql.js', 'absurd-sql']
}
}
}
},
define: {
__DEV__: false,
__TEST__: false,
__PROD__: true
}
}
```
**PWA Configuration**:
```typescript
VitePWA({
registerType: 'autoUpdate',
manifest: appConfig.pwaConfig?.manifest,
devOptions: { enabled: true, type: 'classic' },
workbox: {
cleanupOutdatedCaches: true,
skipWaiting: true,
clientsClaim: true,
sourcemap: mode !== 'production',
maximumFileSizeToCacheInBytes: 10 * 1024 * 1024,
runtimeCaching: mode === 'production' ? [/* API caching */] : []
}
})
```
- **Minimal Configuration**: Inherits all settings from `vite.config.common.mts`
- **Mode Selection**: `--mode test` or `--mode production` (passed by
`scripts/build-web.sh`) selects the matching `.env.*` file
- **Output**: Writes to `dist/`
### B.3 vite.config.electron.mts
@@ -2699,7 +2577,6 @@ export default defineConfig(async () => createBuildConfig('capacitor'));
- **Minimal Configuration**: Inherits all settings from common config
- **Mobile Platform**: Automatically configures for mobile-specific settings
- **PWA Disabled**: Progressive Web App features disabled for native apps
- **Native Dependencies**: Handles Capacitor-specific dependencies
### B.5 vite.config.utils.mts
@@ -2708,51 +2585,15 @@ export default defineConfig(async () => createBuildConfig('capacitor'));
**Author**: Matthew Raymer
**Description**: Utility functions for Vite configuration
**Purpose**: Provides shared configuration loading and PWA manifest generation.
**Purpose**: Provides the shared alias configuration and strict ESBuild settings.
**Key Functions**:
**loadPackageJson()**: Loads and parses package.json for app configuration
**loadAppConfig()**: Returns the alias configuration used by the common and
optimized configs
**loadAppConfig()**: Loads complete application configuration including PWA settings
**PWA Configuration**:
```typescript
interface PWAConfig {
registerType: string;
strategies: string;
srcDir: string;
filename: string;
manifest: {
name: string;
short_name: string;
theme_color: string;
background_color: string;
icons: ManifestIcon[];
share_target: ShareTarget;
};
}
```
**Manifest Icons**:
- Android Chrome 192x192 PNG
- Android Chrome 512x512 PNG
- Maskable icons for adaptive UI
**Share Target Configuration**:
```typescript
share_target: {
action: "/share-target",
method: "POST",
enctype: "multipart/form-data",
params: {
files: [{ name: "photo", accept: ["image/*"] }]
}
}
```
**getStrictESBuildConfig()**: Returns ESBuild settings that fail the build on
syntax and duplicate-declaration errors
**Alias Configuration**:
@@ -2820,8 +2661,7 @@ All scripts use consistent error handling:
**Web Platform**:
- PWA features enabled
- Service worker injection
- Requires a secure context (HTTPS, `localhost`, `127.0.0.1`, or `[::1]`)
- Browser-specific optimizations
**Electron Platform**: