5.8 KiB
3. CLI commands + required installs (per deployment method)
Everything runs through bun and the scripts in package.json. The build loop
iterates every folder under plugin-designs/ (each folder = one bundle), so once a
map exists there, bun run build picks it up automatically — no per-map wiring.
Install once (all methods): Bun (
curl -fsSL https://bun.sh/install | bash) — Node ≥ 18 also works (npm run <script>; the scripts are identical). Then:bun install
The scripts these commands are grounded in (from this branch's package.json):
"dev": "bun x vite",
"build": "bun run clean && bun run token && for d in plugin-designs/*/; do BUNDLE=$(basename \"$d\") bun x vite build || exit 1; done && bun run tree && bun run check:drop && bun run check:drop && bun run check:parse && bun run verify && bun run gallery",
"preview": "bun x vite preview",
"serve": "python3 -m http.server 4173 --bind 0.0.0.0 --directory public",
"cap:sync": "bunx cap sync android",
"cap:verify": "test -f capacitor/android/app/src/main/assets/public/index.html && echo \"OK webDir copied\" || (echo \"FAIL ...\" && exit 1)",
"apk:debug": "bun run build && bun run cap:sync && bun run cap:verify && cd capacitor/android && ./gradlew assembleDebug",
"apk:install": "adb install -r capacitor/android/app/build/outputs/apk/debug/app-debug.apk",
"phone": "bun run apk:debug && bun run apk:install"
bun run build writes the whole deployable tree to public/doxa-maps/, including
manifest.json — the machine-readable index that carries the ready-to-paste
iframe and <script src> + SRI embed snippets for every map.
Summary table
| # | Deploy method | Install first (prereqs) | Command(s) |
|---|---|---|---|
| 1 | iframe embed | Bun | bun install → bun run build → bun run serve (or drop public/doxa-maps/ on any host) |
| 2 | Mobile app (Android) | Bun · Android SDK + adb on PATH · JDK 17 (Gradle) · Capacitor (already a devDep) |
bun run phone (= apk:debug build + apk:install to a connected device/emulator) |
| 3 | Direct-JS / dashboard | Bun | bun run build, then paste the <script src> + integrity (SRI) snippet from manifest.json |
| 4 | WordPress | Bun (build only) | bun run build, then paste the same iframe or script snippet into a WordPress Custom HTML block. (No dedicated WP build script — deferred POC.) |
| 5 | Desktop (Tauri) | Rust toolchain + Tauri CLI (not yet scaffolded) | Deferred POC — no command exists on this branch yet. |
1. iframe embed (required)
Install: Bun.
bun install
bun run build # builds every plugin-designs/* bundle -> public/doxa-maps/
bun run serve # optional: serves public/ at http://localhost:4173
The build writes public/doxa-maps/manifest.json. Each profile carries an
embed.iframe snippet, e.g.:
<iframe src="./all-people-groups/all-people-groups/index.html"
width="100%" height="600"
style="border:none;border-radius:12px;" allowfullscreen></iframe>
URLs are root-relative, so the whole doxa-maps/ folder is position-independent —
drop it on Cloudflare/Vercel/any static host and every iframe resolves. (For an
external absolute base, set embedBaseUrl in the build config before building.)
2. Mobile app — Android / Capacitor (required)
Install: Bun · Android SDK (sdkmanager, adb on your PATH) · JDK 17
(the Gradle wrapper needs it) · Capacitor (@capacitor/* are already devDependencies,
so bun install covers them). A connected device or running emulator for install.
bun run phone
phone chains the whole path: apk:debug (which runs bun run build, then
cap:sync to copy the web output into the Android project, then cap:verify, then
./gradlew assembleDebug) and finally apk:install (adb install -r ...) onto the
device. Run the halves separately if you want to inspect between steps:
bun run apk:debug # build the APK only
bun run apk:install # push the built APK to a connected device
Only Android is scaffolded on this branch (capacitor/android, capacitor.config.json);
iOS is not set up.
3. Direct-JS / dashboard (required)
Install: Bun.
bun run build
Then paste the profile's embed.script snippet from manifest.json — a <script src>
with a Subresource-Integrity (SRI) hash plus the custom-element tag:
<script src="./all-people-groups/all-people-groups.js"
integrity="sha384-j5Ypx+EI9DGlTClzgLs1R8wAnmTnkQ7HgAhHrxyGoVoHDMTlFVY7slU6JNicn77T"
crossorigin="anonymous"></script>
<all-people-groups
profile-config='{"profile":"all-people-groups","tk":"YOUR_MAPBOX_TOKEN"}'>
</all-people-groups>
The element accepts props / emits events, so it can wire into a surrounding page as a unified research dashboard (deploy-3 proof). The SRI hash regenerates on every build.
4. WordPress (deferred POC)
No dedicated WordPress build step exists on this branch. WordPress is served by the same artifacts as methods 1 and 3:
bun run build
Then paste either the iframe snippet or the <script src> + SRI snippet from
manifest.json into a WordPress Custom HTML block. A first-class WP plugin/build
step is a deferred POC (see backlog _meta: "deploy methods 4/5 are DEFERRED").
5. Desktop — Tauri (deferred POC)
Intended prereqs: the Rust toolchain (rustup) + the Tauri CLI, wrapping the same
bun run build web output as a native desktop shell.
Status: deferred POC. No Tauri scaffolding or build script exists on this branch yet, so there is no copy-paste command to run today. Documented here for completeness of the 5-method model.