From meta-vr
Guides shipping a web app to the Meta Horizon Store as a PWA/TWA in 2D or WebXR mode. Covers IWSDK WebXR builds, Vercel deployment, manifest/icons, bubblewrap packaging, keystore/Digital Asset Links, and ovr-platform-util upload.
How this skill is triggered — by the user, by Claude, or both
Slash command
/meta-vr:hz-store-pwaThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide the end-to-end process of wrapping a web app as a Meta Quest app and shipping
Guide the end-to-end process of wrapping a web app as a Meta Quest app and shipping
it to the Meta Horizon Store. This skill covers both delivery modes — a 2D
windowed panel and an immersive WebXR/VR experience — through the same
pipeline: build the web app, deploy to Vercel, add a PWA manifest + icons, package
as a signed Quest APK with @meta-quest/bubblewrap-cli, and upload with
ovr-platform-util.
Commands use <…> tokens (e.g. <DOMAIN>, <HORIZON_APP_ID>, <team-slug>,
<PW>) — substitute your own values before running.
Use this skill when you need to:
@meta-quest/bubblewrap-cliovr-platform-utilFor deeper IWSDK app-building guidance, see the hz-iwsdk-webxr skill. For the
broader Store submission process (VRC compliance, store assets, review tracking),
see the hz-store-submit skill.
The full pipeline follows this order. The two mode-specific deltas are flagged; all other steps are identical for 2D and immersive.
0. Pick app mode → 2D panel vs immersive WebXR (sets steps 1 + 4)
1. Build the web app → IWSDK WebXR app (immersive) OR any responsive PWA (2D)
2. Deploy to Vercel → public HTTPS origin = <DOMAIN>
3. Manifest + icons → installable web app manifest, PNG icons, live on <DOMAIN>
4. Package as APK → bubblewrap: keystore, twa-manifest, build, asset links
5. Upload to the Store → ovr-platform-util upload-quest-build
Dependencies between steps matter — see Order of Operations at the end.
The app mode is the single most important decision, chosen once. It changes exactly two things downstream:
horizonOSAppMode value in twa-manifest.json ("immersive" vs "2D").| 2D PWA | Immersive WebXR PWA | |
|---|---|---|
| Runs as | windowed 2D panel on Horizon | enters a full VR/WebXR session |
| Web app | any responsive PWA (IWSDK optional) | WebXR app (IWSDK is the easy path) |
Auto-enter requestSession | NO — do not add it (Step 1) | YES — built into the app (Step 1) |
horizonOSAppMode | "2D" (Step 4) | "immersive" (Step 4) |
A wrong horizonOSAppMode value is the classic failure mode: a 2D app set to
immersive is stuck loading; an immersive app set to 2D shows a browser URL bar.
See references/app-modes.md for the full decision guide.
Scaffold with @iwsdk/create (the only supported scaffolder):
npx @iwsdk/create@latest <app-name> --yes --mode vr --no-metaspatial \
--no-physics --no-locomotion --grabbing
Toggle --physics (Havok gravity/collisions), --locomotion (roam a large space),
and --grabbing (hands/controllers pick objects up) to fit the app. For arcade-style
apps prefer deterministic manual motion over physics.
Don't reinvent IWSDK app code. The template's bundled CLAUDE.md,
.claude/skills/iwsdk-* skills, and the iwsdk-rag MCP are the source of truth for
imports, ECS, XR input, physics, UI, and debugging. Query those rather than guessing.
Build auto-enter into the immersive app from the start. An installed immersive
PWA opens with no 2D page, so the app itself must start the session on load (the
app-icon tap is the user activation). Gate it on getDigitalGoodsService so it runs
only in the installed PWA, never a browser tab:
const nav = navigator as Navigator & { xr?: { isSessionSupported?: (m:string)=>Promise<boolean> } };
if ("getDigitalGoodsService" in window && nav.xr?.isSessionSupported) {
nav.xr.isSessionSupported("immersive-vr")
.then(s => { if (s) world.launchXR(); }) // IWSDK launchXR == requestSession + setup
.catch(() => {});
}
getDigitalGoodsService is device-only — validate this path on the headset.
Any responsive web app/PWA works — IWSDK is not required. It runs as a single- instance standalone panel with its own Library entry. Make sure it's a valid installable PWA (Step 3) and build/deploy it like any static/SPA site (Step 2). Do NOT add the auto-enter code above.
Full scaffolding flags, project layout, and the auto-enter rationale are in
references/app-modes.md.
The web app must be live on a public HTTPS origin before packaging — bubblewrap
fetches the manifest and icons from it. Set base: "./" in your Vite config, then:
npx -y vercel@latest whoami
npx -y vercel@latest teams ls
npx -y vercel@latest deploy --prod --yes --scope <team-slug>
Two URLs result:
https://<project>.vercel.app → public (200). Use this as
<DOMAIN> everywhere downstream.…-<team>.vercel.app → 401 under deployment protection.
Not for sharing, not usable as <DOMAIN>.Verify the root and manifest both return 200, and that the manifest is served as
application/manifest+json:
curl -s -o /dev/null -w "%{http_code}\n" https://<DOMAIN>/manifest.webmanifest
See references/vercel-deploy.md for details and the
redeploy-vs-rebuild rule.
Both modes need a valid, installable manifest and PNG icons, live on <DOMAIN>
before bubblewrap update runs. Place public/manifest.webmanifest:
{ "name":"…","short_name":"…","description":"…","start_url":"/","scope":"/",
"display":"standalone","orientation":"landscape",
"background_color":"#06010f","theme_color":"#0a0418",
"icons":[
{"src":"/icons/icon-192.png","type":"image/png","sizes":"192x192","purpose":"any"},
{"src":"/icons/icon-512.png","type":"image/png","sizes":"512x512","purpose":"any"},
{"src":"/icons/icon-512-maskable.png","type":"image/png","sizes":"512x512","purpose":"maskable"}]}
Link it in index.html <head> (<link rel="manifest"> + <meta name="theme-color">
<link rel="icon">). For multi-origin 2D apps, add additional_trusted_origins
and host asset links on each origin.There's no ImageMagick/PIL here — generate icons with sharp (npm i -D sharp) from
an SVG. The maskable icon must be full-bleed and opaque (no transparency or rounded
corners). Vite copies public/ into dist/.
See references/manifest-and-icons.md for the
icon script and the full manifest reference.
bubblewrap wraps the live PWA into a signed Android APK (a Trusted Web Activity).
npm i -g @meta-quest/bubblewrap-cli # bin: bubblewrap
Prereqs are pre-provisioned in ~/.bubblewrap (its own JDK 17 + Android SDK). Find
the tools dynamically:
KT=$(find ~/.bubblewrap/jdk -path '*/bin/keytool' | head -1)
BT=$(ls -d ~/.bubblewrap/android_sdk/build-tools/* | sort -V | tail -1)
bubblewrap init uses an interactive inquirer wizard that needs a real TTY. A
non-TTY caller (an agent driving Bash) can't answer it and there are no value flags
to bypass it — use the scripted path below.
Signing keystore — pause and ask the developer which key to use before building. The key is permanent: every future update must reuse it. Either reuse an existing keystore (ask for its path, alias, and passwords — required when updating a published app) or generate a new one outside the deployable web tree.
twa-manifest.json (scripted path) — author it from the authoritative
TwaManifest schema. The critical field:
"horizonOSAppMode": "immersive" // ← "immersive" for WebXR | "2D" for a 2D panel app
A wrong value is the classic failure mode (Step 0). applicationId = numeric
Horizon App ID ("0" builds & sideloads without IAP; set the real id before Store
work).
Build — update regenerates gradle and bumps version; passwords go via env
vars (no password CLI flags exist):
cd <twa-dir>
export BUBBLEWRAP_KEYSTORE_PASSWORD=<PW> BUBBLEWRAP_KEY_PASSWORD=<PW>
bubblewrap update && bubblewrap build
# → app-release-signed.apk + app-release-bundle.aab
"$BT/apksigner" verify --print-certs app-release-signed.apk | grep -i SHA-256 # must == keystore
Digital Asset Links — a TWA "will not launch" if this fails. Host
public/.well-known/assetlinks.json on the same domain (and every trusted
origin), with the package name and the colon-hex cert SHA-256. Redeploy, then
curl https://<DOMAIN>/.well-known/assetlinks.json to confirm.
Security: the keystore and app secret NEVER go to the public host — verify with
curl -o /dev/null -w "%{http_code}" https://<DOMAIN>/android.keystore (expect 404).
Back up the keystore.
Full keystore handling, the complete twa-manifest.json template, build
verification, and asset-link details are in
references/bubblewrap-packaging.md.
hzdb / metavr are device-only and cannot upload. Use ovr-platform-util — the
same command works for 2D and WebXR builds:
./ovr-platform-util upload-quest-build \
--app-id <HORIZON_APP_ID> --app-secret <SECRET> \
--apk app-release-signed.apk \
--channel ALPHA --age-group MIXED_AGES \
--notes "…" --disable-progress-bar
Required: --app-id, --apk, --channel, --age-group
(TEENS_AND_ADULTS | MIXED_AGES | CHILDREN), and --app-secret or --token.
Channels: ALPHA/BETA/RC for testing, STORE for production. Auth is the app's
App Secret (Dashboard → app → API tab) or a user token — ask the user, never
invent it.
Likely first-time blocker: must first agree to our Developer Distribution Agreement — an org admin must sign it once at
https://developer.oculus.com/manage/organizations/<ORG_ID>/legal-documents/. Pause,
ask the user, then retry the same command.
See references/store-upload.md for tool download, auth,
and the DDA blocker.
horizonOSAppMode value (Step 4).bubblewrap update — it fetches them from
<DOMAIN>.horizonOSAppMode mismatch is the #1 failure — "2D" set to immersive hangs
on a loading screen; "immersive" set to 2D shows a URL bar. Fix the value and
rebuild.packageId. A lost keystore means a new app entry. Back it up, and keep it
outside the deployable web tree.bubblewrap init needs a TTY — agents must use the scripted path (hand-written
twa-manifest.json + update + build).launchXR() snippet to a 2D app,
and always gate it on getDigitalGoodsService so it doesn't fire in a browser tab.getDigitalGoodsService is device-only — auto-enter can't be validated in a
desktop browser or emulator; test on the headset.<DOMAIN>./.well-known/assetlinks.json is live with a matching package name and cert SHA-256.sharp icon-generation script.twa-manifest.json template, build verification, asset links, and security.ovr-platform-util download, auth, the
upload command, and the Developer Distribution Agreement blocker.npx claudepluginhub meta-quest/agentic-tools --plugin meta-vrGuides end-to-end Meta Quest and Horizon OS app submission to the Meta Horizon Store — build validation, store-readiness checks, asset preparation, upload, and submission tracking.
Publishes a webapp to Vercel for live HTTPS hosting, enabling on-device access for Meta Display Glasses. Use when ready to ship to a stable production URL.
Builds Progressive Web Apps with offline support, installability, and caching strategies using service workers and web app manifests.