IWSDK WebXR workflow: start here

Made by Navid Mirzaaghazadeh · part of iwsdk-webxr-skills · MIT

This skill only routes. The detailed steps live in the skills it names. Load the named skill before acting on a step.

• Plugin installs prefix skill names (<bundle>:iwsdk-dev). Match on the part after the colon.
• If a named skill isn't installed, say so and point to the library README. Don't improvise its content from memory.
• Scaffolded projects already contain IWSDK's 12 official skills in .claude/skills/. Don't install a second copy.

1. Before anything

1. For Quest, Quest Browser or Horizon Store facts, load hz-quest-verify-first and check Meta's live docs (metavr docs search "<topic>"), not memory.
2. Check the tools and the project, and ask before installing anything:

   node --version                      # >=20.19 <21, >=22.12 <23, or >=24
   npx @iwsdk/cli dev status           # inside an IWSDK app: runtime URLs, browserCommandReady
   adb devices                         # headset connected and authorised

   No project, wrong Node, MCP tools missing → iwsdk-project-setup. An IWSDK 0.4.x project (GLXF, Meta Spatial Editor, vite-plugin-uikitml) → iwsdk-migrate-0-5 first.
3. For any change to app code, scenes, models or UI, invoke iwsdk-dev first. It picks the greenfield or bounded-change playbook and calls the specialists.
4. Target devices. Meta VR Glasses (spring 2027; v207 SDKs out now) use gaze to aim, a hand pinch to select, usually no controllers, and a 70° × 66° view. If the app should run there, load iwsdk-vr-glasses while planning: the input plan changes the design, not just the config.
5. Docs. IWSDK's docs now live on Meta's site (https://developers.meta.com/vr/documentation/iwsdk/guides/overview/, Markdown index at https://developers.meta.com/vr/llmstxt/documentation/iwsdk/llms.txt/), but those pages describe IWSDK 0.5.3 and show some config keys 1.0.1 rejects. When a hosted page and the installed package disagree, the package wins (.d.ts files, npx @iwsdk/cli <domain> --help, npx @iwsdk/cli mcp inspect). Differences: this library's docs/meta-reference/web-iwsdk-docs-on-meta.md; https://iwsdk.dev matches 1.0.1.

2. The path from idea to store

3. Hard rules

• Ask first before: deploying to a public host, any Store upload or channel promotion, scaffolding with --force, installing tools (Node, Playwright browsers, KTX-Software, npm i -g @meta-quest/bubblewrap-cli, OVR Metrics Tool), writing agent config (adapter sync), enabling --allow-browser-automation, or creating a signing key. Store submission happens in the Developer Dashboard, done by the user.
• Secrets: keystores, key passwords, app secrets and deploy tokens never go in public/, dist/, git or chat output. After every publish, check that https://<domain>/android.keystore returns 404. Remind the user to back up the keystore: without it the app can't be updated.
• Prove it in the runtime, then on the device. Typecheck → dev up → ECS/XR evidence (xr status shows sessionActive) → headset. A compile or a flat screenshot isn't proof.
• Versions: all @iwsdk/* packages on one version (1.0.1 = npm latest when checked; 1.1.0-rc.1 on next moves three to super-three 0.185.0: don't adopt it unasked), three aliased to npm:super-three@0.181.0 with an overrides entry, Three.js classes imported from @iwsdk/core.
• One of each: one scaffold (npm create @iwsdk@latest), one entry skill for app code (iwsdk-dev), one release pipeline (horizon-web-store-publish), one verify-first skill (hz-quest-verify-first).
• Conflicting guidance: IWSDK APIs → the installed package, then the iwsdk-* official skills plus skills/iwsdk-official/ERRATA.md (Meta's hz-iwsdk-webxr was written for IWSDK 0.4, see iwsdk-performance/references/older-advice.md; Meta's hosted IWSDK pages for 0.5.3). Store values → the horizon-* skills over hz-store-submit and hz-store-pwa. When in doubt, check live docs.
• Built-ins first: IWSDK already provides grabbing, ray/pointer interaction, UIKitML panels, locomotion, physics and audio. @iwsdk/core 1.0.1 is built on @pmndrs/uikit, @pmndrs/handle and @pmndrs/pointer-events, so use pmndrs-uikit, pmndrs-handle and pmndrs-pointer-events only as low-level references after iwsdk-ui, iwsdk-grab and iwsdk-ray. Don't call pmndrs's forwardHtmlEvents, add a second event forwarder, or run another uikit update loop: IWSDK wires these already (canvas events come from input.canvasPointerEvents), so events would fire twice. Skip their createXRStore and React Three Fiber sections.
• Side effects to mention once: npm install in a scaffold runs @meta-quest/metavr's postinstall (binary into ~/.metavr, a completions line in your shell profile) and enables IWSDK tool-call telemetry through metavr (iwsdk-project-setup §9).

4. Quick router

Sources

• https://iwsdk.dev, https://iwsdk.dev/llms.txt, https://iwsdk.dev/ai/
• https://github.com/facebook/immersive-web-sdk (1.0.1, commit 0778f518): packages/cli/guidance/AGENTS.md, docs/guides/18-platform-services.md
• https://developers.meta.com/vr/documentation/iwsdk/guides/overview/ and https://developers.meta.com/vr/llmstxt/documentation/iwsdk/llms.txt/ (pages dated 2026-09-04 to 2026-09-23, generated from IWSDK 0.5.3)
• https://developers.meta.com/horizon/essentials/get-started-with-glasses/ (2026-10-13), https://developers.meta.com/blog/meta-connect-recap-start-building-the-future-of-vr/ (2026-09-24)
• https://www.npmjs.com/package/@iwsdk/core (latest 1.0.1, next 1.1.0-rc.1, checked 2026-10-17)
• https://developers.meta.com/horizon/resources/vrc-quest-performance-1/

Last verified: 2026-10-17