webspatial-builder build

Used to preview a Packaged WebSpatial App on a test device. It only handles packaging. You still need to use the platform's official tools, such as Xcode, to push the app bundle to the test device, install it, and launch it. visionOS test devices must be registered in advance in the Apple developer account console and in Xcode.

Quick Reference

Item	Value
Best for	Previewing a Packaged WebSpatial App on a personal test device.
Required credentials	--bundle-id and --teamId for visionOS.
Does it upload to a store?	No.

When to Use

• When you want to run a WebSpatial App on a spatial computing platform that does not include WebSpatial Runtime, such as visionOS.
• When you only need to preview the effect on a personal test device.

When Not to Use

• When you want to run on a spatial computing platform that includes WebSpatial Runtime and supports running a WebSpatial App directly by URL, such as PICO OS 6.
• When you only need to preview in a simulator, or when you want to distribute the app widely.

Syntax

Build an app bundle for a test device

webspatial-builder build \
  --bundle-id=<id> \
  --teamId=<id> \
  [--export=<local path>] \
  [--base=<base url>] \
  [--manifest=<local path>] \
  [--manifest-url=<url>] \
  [--project=<dist>]

Option Overview

Option	Required	What it controls
--teamId	Yes for visionOS	Identifies the Apple developer team used to sign the build.
--bundle-id	Yes for visionOS	Selects the registered Apple app identifier.
--export	Optional	Changes the output path of the generated native app bundle.
--base	Optional	Provides or overrides the base URL used to resolve start_url.
--manifest	Optional	Points Builder at a local Web App Manifest file.
--manifest-url	Optional	Fetches the manifest directly from a live site URL.
--project	Optional	Points Builder at a custom website build output directory.

Options

--teamId

Required to preview on a visionOS device. Comes from the Team ID in the developer information of the Apple developer account console.

--bundle-id

Required to preview on a visionOS device. Comes from the Bundle ID obtained by registering the app in the Apple developer account console.

--export

By default, the native app bundle generated by WebSpatial Builder is written to the build/ directory. Use --export to change it to a custom path.

--base

Specifies the base URL for the start URL (start_url) of the current Web App. The default value is "".

If WebSpatial Builder does not know the current Web App's start_url, the value of --base is used directly as start_url.

If the current Web App's start_url obtained by WebSpatial Builder is a relative URL with no domain part, --base can provide the domain and complete the URL.

Resolution state	Runtime behavior
A complete start_url is available	The Packaged App loads HTML/CSS/JS and other Web files from the network at runtime.
A complete start_url is missing	WebSpatial Builder packages the website build output into the native app bundle, and the app loads website files offline from local files inside the bundle at runtime.

If WebSpatial Builder already has the complete start_url for the current Web App, --base can be used to change the base part of start_url.

--manifest

Tells WebSpatial Builder which path in the current project contains the Web App Manifest file. By default it reads from public/manifest.webmanifest or public/manifest.json.

Fields such as start_url in a Web App Manifest are usually relative URLs and do not hardcode the domain or other base URL parts. That means WebSpatial Builder cannot determine how to access the current Web App by URL from the manifest file in the project repository alone. It needs --base to obtain the domain and complete the URL. Otherwise, the generated Packaged App will contain all website build output and will not load the site from the network.

--manifest-url

Tells WebSpatial Builder to fetch the Web App Manifest directly from the live site by URL.

Because this URL includes the domain and other base parts, even if fields such as start_url in the Manifest are relative URLs, WebSpatial Builder can infer and complete start_url automatically just like a browser. In this case, WebSpatial Builder effectively embeds the live Web App into the Packaged App by URL, so local project files and parameters such as --base are not required.

--project

If WebSpatial Builder cannot determine how to access the current Web App by URL, it packages the website build output from dist/ into the native app bundle by default.

You can use --project to make WebSpatial Builder read the website build output from a different path.