Preview locally

Seeing your app's Cockpit screens before you deploy them — what the local devkit loop is for, and where the setup is documented.

cockpit.json is a declaration, so the only way to know it is right is to render it. Deploying to find out is a slow loop and a public one: a wrong column name is a broken screen in a merchant's Cockpit and a five-second fix on your laptop.

The devkit closes that loop. It renders your app's cockpit.json with the real Cockpit renderers against mock data generated from your schema.json, so you see the actual list, detail and form views your declarations produce. No platform, no backend and no account are involved.

The devkit is documented with Commerce Studio: Preview locally. Commerce Studio is the shell that renders these views, so its own tooling is documented there rather than duplicated here — the package, how to boot it, and what it mocks.

What the preview is for

Worth being specific, because it catches a particular class of mistake that no other check does:

Column and field names that do not exist. schema.json says sold_at; cockpit.json says soldAt. Both files validate; the screen is empty. No JSON Schema can catch this, because neither file knows about the other.

A write or an api action pointing at a route you never declared as a capability. The renderer calls your app's own public route, so a missing capability is a failure in the browser. See How the Cockpit renders.

A capability whose request schema is stricter than the form. The form collects three fields; the contract requires four. The operator gets a 400 they cannot explain. This is the same do-not-out-strict-your-contract trap, arriving through the UI.

A settings form nobody can fill in. Fifteen ungrouped switches, a label that is a schema key, a market-scoped setting on an app without the markets dependency.

Icons and labels. An unresolved icon name falls back to a generic box, which you will notice instantly in a preview and never notice in a JSON file.

The loop

The shape of it, whatever the exact commands:

text
edit cockpit.json  ─►  preview  ─►  look at the screen  ─►  edit again
                                        │
                                        └─► once it looks right: revenexx deploy app

Two habits make it worth the setup:

Preview after every structural change, not once at the end. A list view that renders is a list view; four views declared blind are four views to debug at once.

Give the mock data a real shape, and know its limits. The rows come from your schema.json: a check with an in (…) list sets the values a column cycles through, and a references entry makes relation columns resolve. The generator never writes a null and keeps text short, so long labels and empty columns, the screen an operator often gets, only show on a real tenant.

What a preview does not prove

  • Constraints and migrations. Those need a real tenant — see Adapters.
  • That your routes are installed. Routes are written at install time; a preview is not an install. See Publish and install.
  • Composition with other apps. How your sidebar entry sits among a dozen other apps' entries, and whether an id/parent anchor resolves, depends on which apps a tenant has installed. APPS_DIR lets you preview several of your own apps together, but only a tenant shows you everyone else's.

So the sequence is: preview locally, deploy to staging, open the Cockpit there, then production. See Deploying.

Next steps

Was this page helpful?