Pick the stack before you write a line.
Every WebXR project renders with WebGL under the hood, so the real choice is what sits between you and it. Four options are worth knowing, and they are not equally suited to a first project.
| Stack | Choose it when |
|---|---|
| Immersive Web SDK (IWSDK) | You want a working VR or AR project today. It is three.js plus an entity component system, and it ships grab interactions, locomotion, spatial audio, physics and scene understanding rather than leaving you to assemble them. |
| three.js on its own | You are embedding 3D into an application that already exists and you want no opinions imposed on your architecture. You will build input, locomotion and comfort yourself. |
| Babylon.js | You want a batteries-included engine with a strong inspector and first-class TypeScript, and you are comfortable with a larger framework. |
| PlayCanvas or A-Frame | PlayCanvas if you want a hosted visual editor; A-Frame if the experience is simple enough to be mostly markup and the team is web-first rather than 3D-first. |
For a team starting from nothing and targeting headsets, IWSDK is the recommendation, and the reason is not the feature list. It is that the platform holder built it — Meta ships it, on the web stack, under an MIT licence — so the examples, the fixes and the attention are going there.
One caveat worth stating up front: choosing IWSDK means adopting its entity component system and its scene format. That is a real architectural commitment. If your 3D has to live inside an existing React application and answer to its state, raw three.js will fight you less.
The setup, start to finish.
This is the whole thing. It takes minutes, not an afternoon.
Prerequisites. Node.js 20.19.0 or newer, a modern browser, and TypeScript or JavaScript familiarity. A headset is optional at this stage — genuinely optional, not politely optional.
npm create @iwsdk@latestThe scaffolder asks you a handful of questions rather than dumping a generic template: language (TypeScript is the sensible answer), whether the experience is VR or AR, which WebXR features you need, and which core systems to include such as locomotion and grabbing. Answer them deliberately — the AR and VR paths differ in how the session is requested and what the world is anchored to, and changing your mind later is more work than it sounds.
What you get is a small, legible project rather than a maze:
| File | What it is |
|---|---|
iwsdk.config.json | Project configuration |
src/index.ts | World creation and system registration — the entry point |
src/assets.ts, src/components.ts | Asset and component catalogues |
public/scenes/main.iwsdk.scene.json | Scene hierarchy and data |
public/audio/, public/textures/ | Media |
vite.config.ts, tsconfig.json | Ordinary web tooling — it is a Vite project |
Then start it:
npm run devThat opens a CLI-managed dev session with the Vite server on a dynamic port. From here it is a normal web project: hot reload, browser devtools, the loop you already know. That familiarity is most of the argument for the web stack over a game engine.
Testing without a headset on your desk.
The single biggest friction in XR development is that the target device is not the machine you are typing on. IWSDK ships IWER, a built-in WebXR emulator, and on desktop it also falls back to mouse-and-keyboard control automatically. No browser extension, no separate install.
That is enough for scene layout, interaction logic, UI, state and most of the content work. It is not enough for the three things that only a headset can tell you:
- Comfort. Whether your locomotion makes people feel ill is not knowable from a monitor.
- Legibility. Text that is crisp on a 27-inch display can be unreadable through a lens.
- Frame budget. A headset running at 90Hz gives you around eleven milliseconds per frame. Your workstation will happily lie to you about this.
So the working rhythm is: build in the emulator, check on the device at the end of every meaningful chunk. Not once, at the end.
Build in the emulator. Verify on the device. The teams that skip the second half discover their comfort problems in a user test.
To get a build onto a headset you need one thing that trips almost everyone: WebXR only runs in a secure context. HTTPS or localhost, nothing else. A plain HTTP server on your local network will serve the page perfectly and then silently refuse to offer an immersive session. Put a TLS certificate on your dev server or tunnel it.
Five things to get right before the content arrives.
These are cheap now and expensive later. All five are design decisions, not optimisations to do at the end.
- Set a download budget as a number. Not “keep it small”. Decide how many seconds this specific audience will wait, convert it to megabytes at a realistic connection speed, and hold the art to it. Everything about scene complexity follows from that figure.
- Treat memory as the hard ceiling. Browser 3D does not gracefully degrade when it runs out; the tab dies. Budget texture resolution and scene complexity against a mid-range device, not your workstation.
- Design the flat view first. Safari on the desktop and Firefox ship WebXR switched off, and Safari on iPhone does not support it at all. For most visitors the non-immersive view is the product. Design it deliberately.
- Abstract input on day one. Controllers, hand tracking, gaze, and mouse-and-keyboard are four input models and you will need all of them. Retrofitting hands into code that assumed controllers is a rewrite of your interaction layer.
- Decide hosting before you build. HTTPS is mandatory, and if you are shipping compressed assets your host has to be configured to serve them properly. This is the most common cause of “it works locally”.
Best practices that are specific to XR, not to the web.
Plenty of good web habits carry over. These do not have web equivalents, and they are where first XR projects usually go wrong.
Never move the camera without the user asking. Cinematic camera moves that read beautifully on a screen make people physically unwell in a headset. If the view has to move, the user initiates it, and you offer a comfort option — teleport or snap turning alongside smooth locomotion, with snap as the default.
Put UI in the world, at a readable distance. Panels roughly one to two metres away, large type, high contrast. A heads-up display locked to the face is uncomfortable to read and hard to focus on. Test every UI decision through a lens before committing to it.
Give every interactive object a hover state and a sound. In a headset there is no cursor and no tooltip. Feedback is how a person learns what is interactive, and audio does a disproportionate amount of that work for very little budget.
Respect the frame budget as a hard constraint. Dropped frames in a browser are an annoyance. Dropped frames in a headset are a physical symptom. Profile early and treat the budget as a requirement, not a target.
Handle session start and end explicitly. People enter and leave immersive mode mid-session, take the headset off, and switch tabs. State that only exists inside the session will be lost. Decide what persists.
What to ship first.
The most common failure in a first WebXR project is scope, not technology. A useful first release is narrower than it feels:
- One scene, one interaction, one goal. A person arrives, does the thing, and understands why it was in 3D. If you cannot say what that thing is in a sentence, you are not ready to build.
- The flat view finished before the headset view. It is the majority experience, it is easier to test, and it forces the content decisions early.
- A real device in the loop from week one. Not at the end.
- Hosting sorted before the content is signed off. HTTPS, compression, and a link you can actually send someone.
The distribution advantage is the whole reason to be here. If you cannot send the link, none of the rest of it counts.
If your starting point is an existing Unity project rather than a blank folder, the calculation is different and the tooling is different — that is a separate guide.
What this means for a buyer.
Start with the business decision, audience, and evidence the project must produce. Simam Digital can turn that into a focused discovery, prototype, MVP, or production roadmap across AI applications, SaaS platforms, digital twins, real-time 3D, XR, and interactive systems.
