Files

gsxdsm 1b3296d91f feat(FN-1093): add mobile build, PWA, and live reload workflow

- Optimize dashboard Vite output for mobile and include vite/client types in app typecheck
- Add PWA support with manifest, service worker, icons, and client registration hooks
- Add a mobile workspace package with Capacitor config and live-reload scripts for local development
- Add a dedicated GitHub Actions mobile pipeline and update mobile workflow documentation
- Add dashboard tests for build output, mobile scripts, and PWA asset coverage

2026-04-07 23:25:34 -07:00

3.6 KiB

Raw Blame History

Mobile Development Guide

Fusion mobile builds package the dashboard web client into Capacitor shells via packages/mobile/.

Prerequisites

Node.js 22+
pnpm 10+
Xcode (iOS builds)
Android Studio (Android SDK + emulator tooling)
Java JDK 17+ (Android Gradle builds)

Quick Start

pnpm install
pnpm mobile:build
pnpm mobile:ios      # open iOS project in Xcode
# or
pnpm mobile:android  # open Android project in Android Studio

Development with Live Reload

Use the live-reload helpers in packages/mobile/scripts/live-reload.ts:

pnpm mobile:dev:ios
pnpm mobile:dev:android

These commands automatically set:

FUSION_LIVE_RELOAD=true
FUSION_SERVER_URL=http://localhost:5173 (default)

To target a different dev server URL, set FUSION_SERVER_URL before running (or pass --server-url directly to the script):

FUSION_SERVER_URL=http://192.168.1.50:5173 pnpm mobile:dev:android

Building for Production

pnpm mobile:build

This runs:

pnpm --filter @fusion/dashboard build
pnpm --filter @fusion/mobile cap sync

After sync, open native projects for release signing/distribution:

pnpm mobile:ios
pnpm mobile:android

PWA Installation

The dashboard includes a PWA manifest (packages/dashboard/app/public/manifest.json) and service worker (packages/dashboard/app/public/sw.js).

Install from browser:

Chrome: three-dot menu → Install app
Safari (iOS): Share → Add to Home Screen

Service workers require HTTPS (or localhost). PWA install/offline behavior will not work on plain HTTP origins.

CI/CD Pipeline

Mobile CI is defined in .github/workflows/mobile.yml.

Trigger manually via GitHub Actions → Mobile Builds → Run workflow
Also runs on push to main when files under packages/mobile/** or packages/dashboard/** change
Jobs:
- build-web (build dashboard and upload dist/client)
- build-ios (sync/build iOS when packages/mobile/ios/ exists)
- build-android (sync/build Android when packages/mobile/android/ exists)

Artifacts are retained for 30 days.

Replacing PWA Icons

Current icons are placeholders:

packages/dashboard/app/public/icons/icon-192.png
packages/dashboard/app/public/icons/icon-512.png

Generate production icons from logo.svg (example with sharp-cli):

npx sharp-cli -i packages/dashboard/app/public/logo.svg -o packages/dashboard/app/public/icons/icon-192.png resize 192 192
npx sharp-cli -i packages/dashboard/app/public/logo.svg -o packages/dashboard/app/public/icons/icon-512.png resize 512 512

You can also use ImageMagick if preferred.

Troubleshooting

`cap sync` fails

Confirm dependencies are installed: pnpm install
Ensure platform projects have been added (packages/mobile/ios / packages/mobile/android)
Re-run: pnpm mobile:sync

iOS build fails

Verify Xcode version/toolchain compatibility
Open packages/mobile/ios/App/App.xcworkspace in Xcode and resolve signing settings

Android build fails

Verify Java 17+ (java -version)
Confirm Android SDK and Gradle tooling are installed via Android Studio

PWA does not install

Verify HTTPS (or localhost)
Confirm manifest.json and sw.js are served from the built app
Clear old service worker/cache and reload

Script Reference

Root scripts (package.json):

mobile:build
mobile:ios
mobile:android
mobile:dev:ios
mobile:dev:android
mobile:sync

Mobile package scripts (packages/mobile/package.json):

cap
dev:ios
dev:android
build:mobile

3.6 KiB Raw Blame History