Develop

Select your platform

Setup your first WebXR project

In this guide, you’ll learn how to programmatially create your first WebXR project from scratch. By the end of this setup, you’ll have a working IWSDK project with all dependencies installed and a development server running.

What you’ll build

Throughout this getting started guide, you’ll progressively build an interactive WebXR experience that includes:

3D objects and environments

Interactive grabbable elements

Player movement and navigation

Spatial user interfaces

Professional lighting and effects

Before you begin

Before you begin, make sure you have:

Node.js (version 20.19.0 or higher)

A modern web browser (Chrome, Edge, Firefox, or Safari)

Basic familiarity with command line/terminal

Basic knowledge of JavaScript/TypeScript (this guide covers the WebXR and 3D parts)

The following is optional but highly recommended:

A WebXR-compatible headset (Meta Quest, HTC Vive, etc.) for testing your experience immersively. While not strictly required thanks to IWER (the WebXR emulator), having a physical headset provides the best testing experience.

Creating your first project

The interactive project generator is the fastest way to get started. Open your terminal and run:

npm create @iwsdk@latest

This command will download and run the latest version of the project creation tool, which will guide you through setting up your project with the right configuration for your needs.

Understanding the setup questions

The create tool will ask you several questions to customize your project. The exact questions depend on your choices, so let’s walk through the complete flow.

Note: Some questions are only asked for VR or AR experiences, which are called out clearly.

Project name

Project name (iwsdk-app)

This will be the name of your project folder and will also be used in your package.json. If you’re just following along with this tutorial, you can use the default iwsdk-app or a descriptive name like my-first-xr-app.

Language choice

Which language do you want to use?
❯ TypeScript
  JavaScript

TypeScript: Provides type safety, better IDE support, and catches errors at development time. Recommended for most projects.

JavaScript: Simpler setup, no compilation step, good for quick prototypes.

TypeScript is recommended for this tutorial as it provides better development experience and catches common mistakes early.

Experience type

What type of experience are you building?
❯ Virtual Reality
  Augmented Reality

Virtual Reality: Creates a fully immersive virtual environment. Users will be completely immersed in your 3D world.

Augmented Reality: Overlays digital content onto the real world. Users can see virtual objects in their physical space.

For this tutorial, VR is recommended as it provides a more straightforward introduction to 3D concepts and spatial interactions.

WebXR features

Next, you’ll be asked about various WebXR features. Each feature has three options:

No: Don’t include this feature

Optional: Include the feature but make it work if not available

Required: Require this feature (experience won’t work without it)

For VR experiences:

Enable Hand Tracking? - Allows users to use their hands instead of controllers

Enable WebXR Layers? - Advanced rendering optimization for better performance

For AR experiences (additional options):

Enable Hand Tracking? - Same as VR

Enable Anchors? - Persistent positioning of objects in real world

Enable Hit Test? - Detecting surfaces in the real world

Enable Plane Detection? - Finding flat surfaces like floors, walls, tables

Enable Mesh Detection? - Detailed 3D understanding of real-world geometry

Enable WebXR Layers? - Same as VR

For this tutorial, the default choices work well. You can always change these later.

Core features

Locomotion (VR only)

Enable locomotion? (Y/n)

Locomotion allows users to move around in your virtual world using controllers.

Yes: Include movement systems (teleport, smooth movement, turning)

No: Users stay in one place (good for seated experiences)

If you choose Yes, you’ll get a follow-up question:

Deploy locomotion engine on a Worker? (recommended for performance)
❯ Yes (recommended)
  No

Workers run locomotion calculations on a separate thread for better performance. Choose Yes unless you have specific reasons not to.

Scene understanding (AR only)

Enable Scene Understanding (planes/meshes/anchors)? (Y/n)

Scene Understanding helps your AR app understand the real world around it.

Yes: Include systems for detecting surfaces, objects, and spatial anchors

No: Basic AR without advanced world understanding

Grabbing (both VR and AR)

Enable grabbing (one/two-hand, distance)? (Y/n)

Grabbing lets users pick up and manipulate objects in your experience.

Yes: Include one-handed, two-handed, and distance grabbing systems

No: Objects can’t be grabbed or moved by users

Recommended: Yes for interactive experiences.

Physics simulation

Enable physics simulation (Havok)? (y/N)

Physics simulation adds realistic object behavior (gravity, collisions, etc.).

Yes: Objects fall, bounce, and collide realistically

No: Simpler behavior, better performance

Default is No because physics adds complexity. You can enable it later if needed.

Meta Spatial Editor integration

Enable Meta Spatial Editor integration?
❯ No (Can change later)
  Yes (Additional software required)

Choose No for this tutorial. This keeps your setup simple and lets you learn IWSDK’s core concepts through code. You’ll create and position 3D objects entirely through code, which gives you complete control and is perfect for learning the fundamentals.

If you’re interested in visual scene composition tools later, you can explore Meta Spatial Editor after completing the main tutorial.

Development setup

Git repository

Set up a Git repository? (Y/n)

Recommended: Yes. This initializes a Git repository for version control.

Install dependencies

Install dependencies now? (The command to start the dev server will be printed.) (Y/n)

Recommended: Yes. This runs npm install automatically and shows you the command to start the dev server.

Project structure overview

Once the project is created, you’ll see a structure like this:

my-iwsdk-app/
├── src/
│   ├── index.ts         # Application entry point and world setup
│   ├── robot.ts         # Example custom component and system
│   └── panel.ts         # UI panel interaction system
├── ui/
│   └── welcome.uikitml  # Spatial UI markup (compiled to public/ui/)
├── public/
│   ├── audio/           # Audio files (.mp3, .wav, etc.)
│   │   └── chime.mp3
│   ├── gltf/            # 3D models and textures
│   │   ├── environmentDesk/
│   │   ├── plantSansevieria/
│   │   └── robot/
│   ├── textures/        # Standalone texture files
│   └── ui/              # Compiled UI files (auto-generated)
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── vite.config.ts       # Build configuration with IWSDK plugins
└── index.html           # HTML entry point

Key files explained

src/index.ts: This is where your application starts. It creates the ECS world, loads assets, spawns entities, and registers systems - everything happens here.

src/robot.ts & src/panel.ts: Example custom components and systems showing how to create interactive behaviors.

ui/welcome.uikitml: Spatial UI markup that gets compiled to JSON during build for the 3D interface panel. Learn more about UIKitML in Spatial UI with UIKitML.

public/gltf/: Organized folder structure for 3D models, with each model in its own subfolder alongside its textures.

public/audio/: Audio files used for sound effects and spatial audio.

vite.config.ts: Build configuration that includes IWSDK-specific plugins for WebXR emulation, UI compilation, and asset optimization.

What’s next

You now have a complete IWSDK project with all dependencies installed and a clear understanding of the project structure.

Next, you’ll launch your development server and learn how to test your WebXR experience both in a physical headset and using the built-in emulator on your computer.

Did you find this page helpful?