deploy.js

Automated deployment script for Ubox experiences. Uses Puppeteer to drive the Ubox Studio web interface and deploy apps and Uboxes without manual browser interaction.

Run from the project root. Always invoke npx @ubox-tools/deploy-xperience from the experience directory (the one containing apps/ and assets/).

Requirements

• Node.js 18+
• A clipboard utility — only needed when the Monaco/CodeMirror editor API is unavailable:
  • macOS: pbcopy (built-in)
  • Windows: PowerShell Set-Clipboard or clip.exe (both built-in)
  • Linux: wl-copy (Wayland), xclip (X11), or xsel (X11)

Usage

npx @ubox-tools/deploy-xperience [app1 app2 ...] [options]

Options

| Flag | Description | |---|---| | --email <email> | Ubox Studio login email (or UBOX_EMAIL env var) | | --password <pass> | Ubox Studio password (or UBOX_PASSWORD env var) | | --project-name <name> | Override the project name (default: parent directory name) | | --noassets | Skip uploading assets (images, fonts, files) | | --nosource | Skip source injection entirely | | --nosource <files> | Skip specific files (comma-separated, e.g. ubox.js,logic.js) | | --noplayer | Skip Phase 3 — deploy apps only, do not create/update Uboxes | | --ubox-id <id> | Use a pre-existing Ubox by ID — skips search/create (single-app deployments) | | --ubox-id <app>:<id> | Scoped form for multi-app deployments (repeatable) | | --xpace <name> | Xpace (place) to assign the Ubox to — case-insensitive match; defaults to the first available xpace if omitted or not found | | --show | Show the browser window (default: headless) | | --help | Print usage and exit |

Credentials are resolved in this order:

1. CLI flags (--email, --password)
2. Environment variables (UBOX_EMAIL, UBOX_PASSWORD)
3. ubox-credentials.json in the project root
4. Interactive prompt (if the terminal is interactive)

ubox-credentials.json (place in the experience project root):

{
  "email": "[email protected]",
  "password": "secret"
}

Environment variables:

[email protected] UBOX_PASSWORD=secret npx @ubox-tools/deploy-xperience

If a credential is provided by a higher-priority source, the file value for that field is ignored.

Examples

npx @ubox-tools/deploy-xperience                        # Deploy all apps (headless)
npx @ubox-tools/deploy-xperience --show                 # Deploy all apps, show browser
npx @ubox-tools/deploy-xperience mobile                 # Deploy only the mobile app
npx @ubox-tools/deploy-xperience main --noassets        # Deploy main app, skip asset uploads
npx @ubox-tools/deploy-xperience --nosource             # Deploy without re-injecting source
npx @ubox-tools/deploy-xperience --nosource ubox.js    # Skip only ubox.js injection
npx @ubox-tools/deploy-xperience --noplayer             # Deploy apps only, skip Uboxes
npx @ubox-tools/deploy-xperience --project-name "MyProject"
npx @ubox-tools/deploy-xperience mobile --ubox-id 42   # Use existing Ubox #42 for mobile
npx @ubox-tools/deploy-xperience --ubox-id mobile:42 --ubox-id main:99
npx @ubox-tools/deploy-xperience --xpace workshop    # Assign Ubox to "Workshop" xpace

Deployment Phases

Phase 1 — Login

Navigates to studio.ubox.world and signs in. Skipped automatically if a session is already active.

Phase 2 — Application Deployment

Runs once per app (always mobile before main):

1. Find or create the application card by its full name (<ProjectName> <appName>).
2. Upload resources — groups assets by type (Images / Fonts / Files), deletes any existing file with the same name first, then uploads via CDP (bypasses the OS file picker dialog).
3. Configure parameters — reads apps/<appName>/parameters.json; only creates parameters that don't already exist.
4. Inject source — opens the Source editor, iterates the tab list (HTML, CSS, Ubox Events, Workflow, Business logic, Data source) and sets each file's content via the Monaco or CodeMirror API, or via clipboard paste as a fallback.

Phase 3 — Ubox Deployment

Runs once per app:

1. Find or create the Ubox by its full name. Handles the Terms & Conditions modal on first creation.
2. Check "Make public" — enables the public checkbox if not already checked.
3. Install app — switches to the "Available applications" tab, searches for the app card, and clicks Install.
4. Mobile virtual link — for the mobile app, clicks "Open Virtual Ubox Link" and captures the URL from the newly opened tab.
5. Set mobileLink parameter — for the main Ubox (if the app defines a mobileLink parameter), opens "Change params" and writes the captured mobile virtual link.

If the Ubox already exists, installation and parameter changes are skipped; the mobile virtual link is still retrieved so the main Ubox can use it.

When --ubox-id is provided, the search/create step is skipped entirely and the script navigates directly to https://studio.ubox.world/#/ubox/<id>. The same "already exists" logic then applies.

Proxy / Source Transformation

Before injecting source files, generateProxy() applies three transforms to each file:

| Transform | Applies to | What it does | |---|---|---| | Parameter substitution | JS | Replaces const KEY = "value" with const KEY = "{parameter:KEY}" for every key in parameters.json | | Asset path substitution | JS, CSS | Replaces ../assets/file.ext references with {resources:type/file.ext} tokens | | Emoji escaping | JS | Converts non-ASCII characters to \uXXXX Unicode escape sequences | | Local tag stripping | HTML | Removes local <link href> and <script src> tags (CDN URLs are kept) |

Project Layout Expected

<project-root>/
  apps/
    mobile/
      index.html
      style.css
      ubox.js
      workflow.js
      logic.js
      data.js
      parameters.json   (optional)
    main/
      ...same files...
  assets/
    *.jpg / *.png / *.woff2 / ...
  deploy.js

The project name defaults to the directory name of <project-root>. App full names are formed as "<projectName> <appName>" (e.g. "Claude - Slide Puzzle mobile").

Error Handling

On any unhandled error the script:

1. Prints the error message.
2. Saves a screenshot to deploy_error.png in the project root.
3. Exits with code 1.

The browser is kept open after both success and failure so you can inspect the final state. Press Ctrl+C to close it.