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 a tenant you choose, so you see the actual list, detail and form views your declarations produce, with your data in them.

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.

Preview against a tenant with real-shaped data. An empty table renders beautifully. A tenant with a thousand rows, long labels and null values in the columns you assumed were populated is the screen an operator actually gets.

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 that tenant has installed.

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

Next steps

Was this page helpful?