Getting started with Commercit apps

Create an app by entering its name in Developer Dashboard → Apps. Keep the selected organization and generated app identifier: the CLI uses both explicitly.

Install the coordinated local release

The public npm packages are not published by this local V1 implementation. Use the reviewed release bundle supplied for the release candidate. Its release.json binds CLI, compiler, contracts and SDK to one version and verifies every package checksum. The bundle installer finds all four packages; no manual vendor copies are needed.

node ./commercit-release/install.mjs --prefix ./.commercit-cli
node ./.commercit-cli/node_modules/@commercit/app-cli/dist/index.js login \
  --organization-id <organization-uuid>
node ./.commercit-cli/node_modules/@commercit/app-cli/dist/index.js init \
  --name <app-slug> --app <app-slug> --organization-id <organization-uuid> \
  --template app-home --release-bundle ./commercit-release
cd <app-slug>
npm exec -- commercit dev

The browser authorization page displays a short verification code and the exact organization. Approve only the session you started. The CLI stores its expiring session outside the project. CI uses a separately created automation token supplied through COMMERCIT_DEVELOPER_API_TOKEN; browser sessions do not become CI tokens.

init installs dependencies with lifecycle scripts disabled, generates an integrity-bound lockfile, writes the supported Astra App Home starter and links it to an explicit working draft. For an existing project, use:

npm exec -- commercit connect --organization-id <organization-uuid> --app <app-slug>

Supply --draft-id <draft-uuid> when selecting an existing matching draft. Every project has a separate .commercit/project.json binding with its base configuration and revision. It contains no credentials and stays outside source uploads.

When the dashboard creates a successor draft, stop dev and synchronize the current one, then select the successor explicitly:

npm exec -- commercit connect --organization-id <organization-uuid> --app <app-slug> \
  --draft-id <successor-draft-uuid> --switch-draft

This updates the selected configuration while preserving source files. Unsynchronized changes and unresolved requests must be reconciled before switching.

Open the first preview

commercit dev lists only development stores authorized for this app, organization and developer. If none exists, it opens the same test-store creation page used by the dashboard. An explicit selection uses --shop-id <development-store-uuid>; knowledge of a live merchant store ID never grants access.

The command synchronizes configuration, builds locally, uploads immutable source and waits for a separate platform build. It opens App Home in the real Admin Extension Host only after artifact parity and current draft checks pass. The preview shows its development status and expiry. Provider network and secrets are disabled in the sandbox. The URL contains a session identifier, never a reusable credential.

Source and dashboard edits are watched. A successful successor receives a new immutable candidate and a new preview URL. Opening it is explicit so the currently visible form is not replaced automatically. Failure preserves the previous mounted artifact; stale, expired or closed sessions cannot obtain new runtime authority. Use --once for a single build, or --no-browser to keep the URL in the terminal.

If a request is interrupted, keep .commercit and run commercit reconcile-build or commercit reconcile-preview as directed. These commands read the original operation. Adding --retry explicitly replays only its saved request after readback; it does not upload newer local work under the old identity.

Edit one draft from both places

Use Releases → draft for configuration and Astra selection, or edit commercit.json. commercit sync, dev and deploy merge disjoint changes against the last synchronized base. Competing edits report their field paths and preserve both sides; choose the intended local value and synchronize again. There is no force-save or silent last-writer-wins path.

Only manifest-owned fields synchronize. Unrelated local fields and files are preserved. Unsupported manifest fields still fail validation; preservation does not make them valid runtime configuration. JSON comments are not supported.

Stable major is the Astra default. An exact pin never updates automatically, including for security fixes. Select a successor explicitly in a draft, synchronize, test and release it. commercit.astra.json records the checked immutable build selection. An unavailable or revoked pin fails closed without changing the policy.

Prepare and release

npm run typecheck
npm test
npm exec -- commercit deploy
npm exec -- commercit submit
npm exec -- commercit review
npm exec -- commercit publish --confirm

Deploy rebuilds and registers an immutable candidate from the connected draft. Submission, review, publication and automatic rollout use the existing publisher lifecycle. The CLI selects the connected draft’s exact current candidate; a semantic version label cannot choose another draft. Editing configuration never changes the active production release directly.

The connector starter is a non-Astra managed worker example. Its development flow creates a scoped API validation session instead of inventing an App Home. Existing OAuth clients retain their declared access-policy workflow. The extension starter uses host components; shipping retains the reviewed carrier scaffold and its explicit package-artifact manifest option. See the CLI reference.

This source/local acceptance does not publish packages, deploy APIs, migrate a remote database, install a merchant app or open external developer signup. Those remain separate authorized release actions.