Skip to main content

Step 1: Install the WebSpatial SDK

Core runtime dependencies​

npm install @webspatial/react-sdk @webspatial/core-sdk @google/model-viewer three
info

@google/model-viewer and three are dependencies used inside the SDK, but their package sizes are relatively large compared to the SDK itself. Plus, many web projects might already use them, and having multiple versions installed could cause conflicts. In the future, the SDK might remove direct dependencies on them. So, they're declared as peerDependencies for now, you'll need to install them explicitly in your web project.

@webspatial/react-sdk​

The SDK offered by WebSpatial for React, which can be plugged into existing regular React projects to enable immediate use of the WebSpatial API.

@webspatial/core-sdk​

Both the React SDK (and forthcoming SDKs for other Web frameworks) are implemented on top of the Core SDK. The Core SDK is a framework-agnostic, lower-level pure-JS API that relies internally on a non-standard JS Bridge API so that the WebSpatial App Shell can natively spatialize 2D HTML content and render 3D content.

Core build-time dependencies​

npm install -D @webspatial/builder

@webspatial/builder​

WebSpatial's packaging tool turns your website into a Packaged WebSpatial App. It's the must-have dev tool right now for developing, testing, and distributing WebSpatial apps on visionOS.

See "Step 2: Add the WebSpatial App Build Tool" for how to use it.

Optional core build-time dependencies​

These optional dependencies let each Web project include only the platform support it actually needs, keeping builds lean.

@webspatial/platform-visionos​

npm install -D  @webspatial/platform-visionos

Includes the WebSpatial App Shell needed to generate a visionOS app and provide spatial capabilities.

note

This package is currently required, as visionOS is the sole spatial computing platform supported by WebSpatial at this stage.

Install Xcode and the visionOS Simulator

To build and package a visionOS app and debug it in the visionOS simulator, you need to install the relevant global dependencies: Xcode and the visionOS Simulator.

Prerequisite: a Mac computer

Steps:

  1. Open the Mac App Store, search for "Xcode", and install it.
  2. On first launch, agree to the license and enter the admin password to install additional components.
  3. Click the top menu "Xcode" > "Settings…". In the "Components" tab, find visionOS and visionOS Simulator under "Platform Support", then install both.

Non-core build-time dependencies​

These plugins integrate with popular third-party toolchains to simplify setup and apply essential performance optimizations and sensible defaults.

@webspatial/vite-plugin​

If you use a React + Vite project:

npm install -D @webspatial/vite-plugin

WebSpatial's Vite plugin adds the required optimizations and defaults when your Web project uses Vite as its web build tool and web server.

@webspatial/next-plugin​

If you use a React + Next.js project:

npm install -D @webspatial/next-plugin

WebSpatial's Next.js plugin adds the required optimizations and defaults when your Web project is based on Next.js framework.

@webspatial/rsbuild-plugin​

If you use a React + Rsbuild project:

npm install -D @webspatial/rsbuild-plugin

WebSpatial's Rsbuild plugin adds the required optimizations and defaults when your Web project uses Rsbuild as its web build tool and web server.

@webspatial/rspack-plugin​

If you use a React + Rspack project:

npm install -D @webspatial/rspack-plugin

WebSpatial's Rspack plugin adds the required optimizations and defaults when your Web project uses Rspack as its web build tool and web server.