Skip to content

Commit ff45c06

Browse files
fadi-georgefadi-george
committed
docs(demo): add README with run instructions
1 parent db03a91 commit ff45c06

1 file changed

Lines changed: 101 additions & 0 deletions

File tree

‎examples/demo/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# OneSignal Capacitor Demo
2+
3+
Reference app for the `@onesignal/capacitor-plugin`. Use it to exercise the SDK on a real device or simulator and to reproduce/debug issues against the local plugin sources at `../../`.
4+
5+
---
6+
7+
## Prerequisites
8+
9+
- Bun, Xcode (with a booted simulator), and Android Studio (with an emulator or attached device)
10+
- `vp` (Vite+) on `PATH` — the demo uses it instead of running `bun`/`vite` directly. Install with:
11+
12+
```bash
13+
# macOS / Linux
14+
curl -fsSL https://vite.plus | bash
15+
16+
# Windows (PowerShell)
17+
irm https://vite.plus/ps1 | iex
18+
```
19+
20+
See the [Vite+ install guide](https://viteplus.dev/guide/#install-vp) for other platforms.
21+
22+
- A OneSignal app id
23+
24+
Copy `.env.example` to `.env` and fill in your app id (and REST API key if you plan to send notifications from inside the demo):
25+
26+
```bash
27+
cp .env.example .env
28+
```
29+
30+
```env
31+
VITE_ONESIGNAL_APP_ID=<your_app_id>
32+
VITE_ONESIGNAL_API_KEY=<your_rest_api_key>
33+
VITE_ONESIGNAL_ANDROID_CHANNEL_ID=
34+
VITE_E2E_MODE=false
35+
```
36+
37+
---
38+
39+
## Run modes
40+
41+
There are two ways to run the demo. Both rebuild the local plugin from `../../` first (via `setup.sh`), so any change you make to the plugin sources is picked up automatically.
42+
43+
| Script | What it does | When to use |
44+
| --------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
45+
| `vp run android` / `vp run ios` | Bundles the web app to `dist/`, syncs into the native project, installs and launches | You only changed native (Kotlin/Swift) code, or you want a "clean" install that mirrors a release build |
46+
| `vp run dev:android` / `vp run dev:ios` | Same install, but the WebView loads from a Vite dev server with HMR + React Fast Refresh | You're iterating on TypeScript/React. Save a file and the WebView updates without a reinstall |
47+
48+
Both modes prompt you to pick a device/simulator if more than one is available.
49+
50+
### Standard (non-dev)
51+
52+
```bash
53+
vp run android
54+
# or
55+
vp run ios
56+
```
57+
58+
The webview loads the prebuilt bundle from inside the app. JS edits require re-running the script. Native code changes always require this path (or a fresh `dev:*` run, which performs a sync).
59+
60+
### Dev (live reload)
61+
62+
```bash
63+
vp run dev:android
64+
# or
65+
vp run dev:ios
66+
```
67+
68+
What happens:
69+
70+
1. `setup.sh` rebuilds the plugin and installs it.
71+
2. The script starts a Vite dev server on `http://localhost:5173` (or reuses one that's already listening — useful if you'd rather run `vp run dev` in a separate terminal for cleaner logs).
72+
3. Capacitor installs the app with `--live-reload --host localhost --port 5173`. On Android it also calls `adb reverse` so the device's `localhost` resolves to your machine.
73+
4. Save a `.ts`/`.tsx` file → HMR pushes it into the WebView.
74+
75+
`Ctrl+C` tears down the Vite server only if the script started it. If you started Vite yourself, that one keeps running.
76+
77+
Notes:
78+
79+
- **Native changes still need a reinstall.** HMR only covers JS/CSS. Editing Kotlin/Swift means re-running `dev:*` (or `android` / `ios`).
80+
- **JS plugin changes require restarting `dev:*`.** `setup.sh` rebuilds and reinstalls the plugin tarball, and also invalidates Vite's prebundle cache + kills any stale Vite on `:5173` so the new code is picked up. The next `dev:*` run starts Vite fresh.
81+
- **Override the port** with `DEV_PORT=5174 vp run dev:android` if `5173` is taken.
82+
83+
---
84+
85+
## Other scripts
86+
87+
| Script | Purpose |
88+
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
89+
| `vp run setup` | Build the plugin, pack it, install into the demo, `vp build`, `cap sync`. Runs automatically before `android` / `ios` / `dev:android` / `dev:ios`. |
90+
| `vp build` | Build the web bundle into `dist/` only. |
91+
| `vp run clean:android` | Wipe Android build outputs (`android/app/build`, `.cxx`, `android/build`). |
92+
| `vp run clean:ios` | Wipe iOS build outputs and SPM checkouts. |
93+
94+
---
95+
96+
## Troubleshooting
97+
98+
- **App stuck on splash (`dev:*`)** — the Vite dev server isn't reachable from the device. Confirm `http://localhost:5173` works in your host browser, then re-run `dev:*`. On a physical Android device, `adb reverse` (handled via `--forwardPorts`) requires `adb` to see the device as `device`, not `offline`.
99+
- **`Invalid target ID` / device shows as `offline`** — `adb kill-server && adb start-server`, then re-run.
100+
- **Plugin changes not showing up in the WebView** — kill the script with `Ctrl+C` and re-run `dev:*`. `setup.sh` will rebuild the plugin, drop `node_modules/.vite/`, and start Vite clean.
101+
- **iOS WebView won't connect to Safari Web Inspector** — make sure the simulator is booted before running `dev:ios`. `webContentsDebuggingEnabled: true` is already set in `capacitor.config.ts`.

0 commit comments

Comments
 (0)