webspatial-builder publish

Used to submit a Packaged WebSpatial App to an app store. It includes packaging and automatically uploads the app to the store after packaging. For the visionOS App Store, app information must be filled in beforehand in App Store Connect.

Quick Reference

Item	Value
Best for	Publishing a Packaged WebSpatial App to an app store.
Required credentials	--u, --p, --version, --bundle-id, and --teamId for visionOS.
Does it upload to a store?	Yes, automatically after packaging.

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 want to test on many real devices or distribute the app publicly.

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 preview on a personal test device.

Syntax

Package and upload an app-store build

webspatial-builder publish \
  --u=<username> \
  --p=<password> \
  --version=<app version> \
  --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
--u	Yes for visionOS	Provides the Apple developer account email used for upload.
--p	Yes for visionOS	Provides the app-specific password for the Apple developer account.
--version	Yes for visionOS	Sets the app version uploaded to App Store Connect.
--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

--u

Required to submit to the visionOS App Store. Comes from the account email in the developer information of the Apple developer account console.

--p

Required to submit to the visionOS App Store. Comes from the app-specific password of the Apple developer account.

--teamId

Required to submit to the visionOS App Store. Comes from the Team ID in the developer information of the Apple developer account console.

--bundle-id

Required to submit to the visionOS App Store. Comes from the Bundle ID obtained by registering the app in the Apple developer account console.

--version

Required to submit to the visionOS App Store. It must be greater than the version already submitted to App Store Connect.

--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.