Develop

Chapter 1: Project Setup

Updated: Jul 22, 2026

Welcome to the Immersive Web SDK! In this first chapter, you’ll learn how to create your first WebXR project from scratch. By the end of this chapter, 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

But first, let’s get your development environment set up!

Prerequisites

Before we begin, make sure you have:

Node.js (>=20.19.0 <21, >=22.12.0 <23, or >=24) - Download Node.js⁠

A modern web browser, such as Chrome, Firefox, or Edge

Basic familiarity with command line/terminal

Basic knowledge of JavaScript/TypeScript (we’ll teach you the WebXR and 3D parts!)

Optional but Highly Recommended

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

Meta Spatial Editor (Optional)

For this tutorial, we recommend skipping Meta Spatial Editor integration. You can build amazing WebXR experiences purely with code, which is what we’ll teach you in this guide. If you’re interested in visual scene composition tools later, check out Chapter 9: Meta Spatial Editor after completing the core tutorial.

Creating Your First Project

The fastest way to get started with IWSDK is using our interactive project generator. Open your terminal and run:

npm create @iwsdk@latest

This command will download and run the latest version of our 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 this guide walks through the complete flow. Note: Some questions are only asked for VR or AR experiences, and the guide identifies those questions.

Project Name

Project name (iwsdk-app)

This will be the name of your project folder and will also be used in your package.json. Choose something descriptive for your project. For this tutorial, you can use the default iwsdk-app or something 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.

We recommend TypeScript 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, we recommend choosing VR 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 such as gravity and collisions.

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 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 Chapter 9: 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? (We will print the command to start the dev server.) (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 and 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. We’ll learn more about UIKitML in Chapter 10: 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.

Starter Dev Commands

Fresh starters ship the iwsdk CLI through @iwsdk/cli, so the default commands are:

npm run dev starts the CLI-managed dev session, opens the app, and keeps the terminal attached

npm run dev:runtime is the internal runtime script the CLI launches

npx iwsdk dev status shows the current runtime URL/port and adapter state

npx iwsdk dev down stops the managed runtime if you started it in the background

Vite chooses the actual dev-server port, so treat the reported runtime URL as the source of truth instead of hard-coding a port.

What’s Next

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

In Chapter 2, we’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.