ed84a728c2
- 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
142 lines
3.6 KiB
Markdown
142 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
FUSION_SERVER_URL=http://192.168.1.50:5173 pnpm mobile:dev:android
|
|
```
|
|
|
|
## Building for Production
|
|
|
|
```bash
|
|
pnpm mobile:build
|
|
```
|
|
|
|
This runs:
|
|
|
|
1. `pnpm --filter @fusion/dashboard build`
|
|
2. `pnpm --filter @fusion/mobile cap sync`
|
|
|
|
After sync, open native projects for release signing/distribution:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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`
|