Support/Builder Guide/Run Puck locally and assign data bindings
/

Builder Guide

Run Puck locally and assign data bindings

Open canonical BuildWithHQ page JSON in a self-contained local Puck editor, assign registered binding keys, and save a validated unpublished draft without exposing credentials to Vite.

Editor
Puck 0.23.0
Browser access
Local files only
Remote save
Trusted Node command

Developer Kit 1.14.2 contains a complete local Puck editor under local-puck/. It uses the same pinned Puck adapter, canonical page conversion, component catalogs and validation rules as the hosted BuildWithHQ designer. It is not a lookalike editor and it does not introduce another page format.

Download Developer Kit 1.14.2Convert existing HTML firstComponent and theme guide
Note

The local browser opens and downloads files only. It receives no app credential, tenant data, database route, user identity, DataRole or Location. A separate Node command performs the optional authenticated draft save.

Start the local editor

Windows PowerShell

Expand-Archive .\BuildWithHQ-API43-Developer-Kit-1.14.2.zip .\bwhq-kit
cd .\bwhq-kit\local-puck
npm ci
npm run dev

Linux or macOS

unzip BuildWithHQ-API43-Developer-Kit-1.14.2.zip -d bwhq-kit
cd bwhq-kit/local-puck
npm ci
npm run dev

Open http://127.0.0.1:4175. The server binds only to loopback and applies a restrictive local Content Security Policy. Dependency versions are pinned in package-lock.json, so use npm ci.

Assign a binding visually

  1. Select Open page JSON and choose a converted or existing canonical page file.
  2. Select the block that should receive live data.
  3. Choose a shipped key in API data binding key (optional). The closed list comes from catalog/bindings.json, not a guessed module name.
  4. Choose its bounded child path in Nested API data path (optional).
  5. Use Advanced only when this SaaS has separately installed a registered binding that is not in the distributed golden catalog. Manual text still has to pass real server validation.
  6. Select Save draft or Download JSON. Both produce canonical BuildWithHQ page JSON; neither publishes.
{
  "_id": "home-work-table",
  "_type": "core.presentation-grid",
  "bindingKey": "work-orders.presentation",
  "dataKey": "table",
  "props": {}
}

Multiple blocks can reuse one binding and select different children. For example, a page can bind metrics, progress, a table and timeline to work-orders.presentation while choosing metrics, byStatus, table and timeline through each block's dataKey. The server executes the binding once under the signed-in user's real scope; the browser does not load a broad dataset and aggregate it itself.

Note

capabilities.json inventories modules and API routes; it is not an installed-binding registry. The separate bindings.json file contains the three presentation bindings shipped by the current golden tenant template: Work Orders, Checklists & Signoffs, and Contacts.

What the editor can and cannot create

Local actionResult
Set bindingKeyReferences an already installed and active server binding.
Set dataKeySelects a bounded property from that binding's returned JSON document.
Type an unknown keyDoes not create an API or SQL query; real server validation rejects the draft.
Download JSONWrites a local canonical page document suitable for Git review, Puck, Monaco or the draft API.
Save through the trusted commandUses the current page-version fence, creates immutable draft history and immediately runs server validation.
PublishNot available in the local editor or draft command. Publication requires a separate live credential and exact validated history.

Save and validate a real unpublished draft

Keep the bwk_draft_ credential in the terminal environment. Never put it in a VITE_* variable, frontend source, page JSON, browser storage or Git.

Windows PowerShell

$env:BWHQ_SAAS_APP_ID = Read-Host "SaaS app ID"
$env:BWHQ_DRAFT_CREDENTIAL = Read-Host "Draft credential"
npm run save-draft -- --page .\home.page.json --page-key Home `
  --change-note "Local Puck binding edit"

Linux or macOS

read -rp "SaaS app ID: " BWHQ_SAAS_APP_ID && export BWHQ_SAAS_APP_ID
read -rsp "Draft credential: " BWHQ_DRAFT_CREDENTIAL && export BWHQ_DRAFT_CREDENTIAL
npm run save-draft -- --page ./home.page.json --page-key Home \
  --change-note "Local Puck binding edit"

save-draft.mjs calls the real Developer API. It gets the current pageVersion, saves with expectedPageVersion, then calls validation and returns the immutable pageHistoryId. A validation failure exits non-zero. The command never publishes and never logs the credential.

Important

A page can only reference a registered binding. Creating a new binding is a separate reviewed template/application contract. It must define a bounded operation and output shape and retain server-derived SaaS, AppAccount, user, DataRole and Location scope.

Verify before use

npm ci
npm run build

The Developer Kit release gate also compares the distributed Puck adapter and page runtime with their production sources, hashes every local-editor file in the integrity manifest, and builds the extracted app before release.