Layouts are a collection of blocks that create a page - for example your home page. You can preview a layout stored on the server, or author one entirely locally, using the Tapcart CLI.

Previewing a server layout

Preview a layout stored on the server with:

tapcart dev layout [target]   # target = layout ID or screen type; omit to pick interactively
tapcart dev layout home       # e.g. preview the home-screen layout

By default, the dev server renders the layout with the server version of every block. To preview it with local block versions instead, use the block toggles in the dev server's browser UI — this replaced the old --block/--all CLI flags. Locally-overridden blocks are visibly marked in the preview, and you can compare the local and live versions of the layout side by side.

📘

Note

tapcart dev is a single unified command for previewing blocks, components, and layouts — the previous per-noun tapcart layout dev, tapcart block dev, and tapcart component dev commands have been replaced by tapcart dev layout, tapcart dev block, and tapcart dev component.

Mocking layouts locally

Compose and preview layouts entirely from your local block and component folders, without touching the dashboard. Define layouts as JSON files and preview them with the dev server.

Layout files

Layout files are stored in .tapcart/layouts/<name>.json — one file per layout. Each layout is a JSON object that references blocks and components by folder name and arranges them into a page:

{
  "contentLayout": "list",
  "blocks": [
    { "use": "ButtonBlock", "as": "cta", "config": { "text": "Shop now" } },
    { "use": "ProductGrid" }
  ]
}

For tabbed layouts:

{
  "contentLayout": "tabbed-list",
  "tabs": [
    {
      "title": "New",
      "blocks": [
        { "use": "ProductGrid" }
      ]
    }
  ]
}

Each block entry supports:

• use — the folder name of a local block or component (non-empty string)
• config (optional) — a partial manifest config object merged over the block's defaults
• as (optional) — a stable handle for addressing repeated blocks (non-empty string)

contentLayout must be exactly "list" or "tabbed-list" — "list" layouts require blocks, "tabbed-list" layouts require tabs (the two are mutually exclusive). All layout objects are validated strictly — unrecognized keys will fail tapcart layout validate.

Layout commands

tapcart layout new <name> [--tabbed]
tapcart layout add <use> [--layout <name>] [--tab <title>] [--pos <i>] [--as <handle>] [--config '<json>']
tapcart layout set <name> <handle> <key=value...>
tapcart layout reorder <name> <from> <to>
tapcart layout remove <name> <handle>
tapcart layout tab add|remove|rename <name> ...
tapcart layout list
tapcart layout show <name>
tapcart layout validate [name]

All commands accept --json to output results in a parseable format — useful for scripts and tools that need to manipulate layouts programmatically.

The tapcart layout validate command checks a layout against the schema and confirms that every use reference resolves to a local block or component folder. A $schema reference is written into each layout file for editor autocomplete.

Previewing a local layout

Once a layout file exists at .tapcart/layouts/<name>.json, preview it with:

tapcart dev layout <name>

This renders the layout through the same pipeline as a layout stored on the server, including mock data from the project-root mockData.json.

📘

Note

While the development server for blocks supports hot reloading, the layout dev server does not support hot reloading of individual blocks.