BizzPocket

Layouts and page types

On this page

A layout is a JSON file that lists the blocks of one page, in order. Your theme ships a default layout for each page in layouts/, plus layouts/global.json for the header and footer. This page lists every page type and its URL, every key of the layout JSON, and how a seller's saved layouts relate to yours.

Contents: Page types and URLs · The page layout · The global layout · Block nodes · Visibility and hiding · Saved layouts and yours · Never rename a block folder


Page types and URLs

The file name of a layout is its page type: layouts/product.json is the product page. The storefront turns each URL into a page type and a page identifier, then renders that page type's layout.

pageType Storefront URL pageIdentifier In bizzpocket dev
home / home yes
product /products/<handle> the product handle yes
shop /shop shop yes
category /categories/<slug> the category slug yes
collection /collections/<slug> the collection slug yes
search /search?q=... search yes
cart /cart cart yes
wishlist /wishlist wishlist yes
account /account account yes (empty data)
orders /orders orders yes (empty data)
order_detail /order/<id> the order id yes (empty data)
order_return /order/<id>/return the order id yes (empty data)
order_cancel /order/<id>/cancel the order id yes (empty data)
login /account/login login yes
signup /account/signup signup yes
policies /privacy, /terms, /shipping, /refund, /returns, /cancellation-policy, /cookie-policy, /disclaimer, /faq (and aliases such as /privacy-policy) which policy: privacy, terms, shipping, refund, returns, cancellation-policy, cookie-policy, disclaimer or faq yes
blog /blog (also /blogs, /news) blog yes
blog_detail /blog/<slug> the post slug yes
content /about, /contact, /pages/<slug> about, contact or the page slug yes
not_found any unknown URL (status 404) not-found yes
checkout /checkout checkout no

Notes:

  • Old URLs redirect. /p/<handle> and /product/<handle> go to /products/<handle>; /c/<slug> and /category/<slug> go to /categories/<slug>; /collection/<slug> goes to /collections/<slug>.
  • Category and collection pages add the slug to page.route.filters as category, so a listing block can scope itself by the path.
  • checkout is owned by the storefront. Every store gets the same checkout page. Do not ship a checkout.json.
  • Account pages. /account, /account/orders and /account/wishlist show the storefront's own page inside your header and footer. Your account, orders, order_detail and wishlist layouts are used at the URLs in the table and in the seller's Customize preview (with a sample shopper).
  • Optional pages. A finished theme ships the commerce pages (home, product, shop, category, collection, cart, account, orders, order_detail, wishlist, search, policies). The others (login, signup, not_found, order_return, order_cancel, blog, blog_detail, content) are optional: without your layout, the storefront shows a plain page of its own (and /blog returns 404).
  • bizzpocket dev serves every URL in the table except /checkout, the old URLs too (it serves them in place instead of redirecting). Every other URL gets the not_found page. The shopper's own pages (account, orders, order_*, login, signup) are never cached. Under dev --mock there is no signed-in shopper: their layouts render, and blocks that ask for the shopper's data get null (render an empty or signed-out state).

A block reads the URL values from page.route in data() and ctx.route in render: pageType, handle (the product, category, collection, post or page handle from the path), q, page, sort and filters (every other query parameter, without tracking ones such as utm_* and gclid). See data.md.


The page layout: layouts/<page>.json

An example layouts/home.json (its types must be blocks of your theme, or the build stops with UNKNOWN_LAYOUT_BLOCK):

json
{
  "schemaVersion": 2,
  "pageType": "home",
  "pageIdentifier": "home",
  "themeId": "my-theme",
  "blocks": [
    {
      "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1a01",
      "type": "hero-banner",
      "props": { "headline": "Toys that make every day playful" }
    },
    {
      "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1a02",
      "type": "announcement-bar",
      "props": { "message": "Summer sale ends Sunday" },
      "hidden": true
    }
  ]
}
Key Required What it is
schemaVersion yes 1 or 2. Use 2 (what init and add-to-layout write): it allows hidden. 1 is the older shape, still accepted.
pageType yes The page type. Write the file name here ("home" in home.json).
pageIdentifier yes Non-empty text. Write the page type here too (content.json may say "about"). The storefront sets the real identifier from the URL.
themeId yes Your theme's id: the id in theme.config.ts.
blocks yes The page's blocks, top to bottom. See Block nodes.
meta no { title?, description?, canonical? } for the page's head.
foreignThemes no Only in saved layouts that borrow blocks from another theme. Leave it out.
themeVersion no Do not write it. The build stamps the version from package.json on every layout.

The build checks each file. These stop it:

  • a file name that is not a page type or global, a block id that is not a UUID, two blocks with the same id, or hidden in a schemaVersion: 1 file: INVALID_MANIFEST (troubleshooting.md);
  • bad JSON: INVALID_LAYOUT_JSON;
  • a node whose type names no block of your theme: UNKNOWN_LAYOUT_BLOCK, with the file and the JSON path of the node (layouts/home.json blocks[1].type) (troubleshooting.md);
  • a pageType that is not the file name: LAYOUT_PAGE_TYPE_MISMATCH (troubleshooting.md).

It warns when a page lacks a block with the role it expects (blocks.md).

Limits for a schemaVersion: 2 layout: at most 150 blocks (children included), 256 KB of JSON, and 10 levels of nesting.

Use bunx bizzpocket add-to-layout <block> [--page <pageType>] to append a block with a new id and its defaults, instead of writing the JSON yourself.


The global layout: layouts/global.json

The header and footer are the same on every page. They live in one global layout, not in each page. An example layouts/global.json:

json
{
  "schemaVersion": 2,
  "themeId": "my-theme",
  "regions": {
    "announcement": [
      { "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1b03", "type": "announcement-bar", "props": {} }
    ],
    "header": [
      { "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1b01", "type": "header", "props": {} }
    ],
    "footer": [
      { "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1b02", "type": "footer", "props": {} }
    ]
  }
}
Key Required What it is
schemaVersion yes Always 2.
themeId yes Your theme's id.
regions.header yes Exactly one block: the header.
regions.footer yes Exactly one block: the footer.
regions.announcement no Blocks for a strip above the header.
themeVersion no Stamped by the build, like page layouts.

Both storefronts render the regions in this order: announcement, header, the page's blocks, then footer. The ids are UUID v4 and must not repeat across the regions.

If a theme has no global.json, the build takes the first header block and the first footer block (by role) from layouts/home.json and builds one. If it finds neither, it stops with NO_GLOBAL_LAYOUT. Older themes still put the header and footer in every page layout; the storefront then shows the global ones in their place. New themes: put them in global.json only.

Block data works the same in both layouts: the needs of the global blocks are fetched in the same page call as the page's.


Block nodes

Every entry in blocks (or in a region) is a node:

json
{
  "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1a01",
  "type": "hero-banner",
  "props": { "headline": "Toys that make every day playful" },
  "visibility": { "devices": ["mobile", "tablet", "desktop"] },
  "hidden": false
}
Key Required What it is
id yes A UUID (version 4 in schemaVersion: 2), unique in the layout. The seller's edits and your theme's starter content refer to the block by it. Never reuse or change it.
type yes The block's folder name (lowercase, digits and dashes).
props yes The starting values of the block's fields. A missing or invalid value uses the field's default. {} is fine.
hidden no true keeps the block in the layout but does not render it (and does not fetch its data). schemaVersion: 2 only.
visibility no { devices?, abTest? }. See Visibility and hiding.
children containers The blocks inside a container block (one with f.blocks()). A container node always has children, even []; any other node never has the key. See group.md.
variantId no Which variant of a legacy type to use (blocks.md). New themes leave it out.
look no Only on blocks borrowed from another theme in a saved layout. Leave it out.

No other key is allowed.

Route props: "placeholder"

On a product page, a prop whose value is exactly "placeholder" in handle is replaced by the URL's product handle, and in productId by the product's id. A block whose type is or starts with product-detail, product-gallery, product-info or product-description always gets the URL's handle. A new block can read page.route.handle in data() instead (data.md).


Visibility and hiding

  • hidden: true removes the block from the page. It is what the eye toggle in the seller's editor sets, and what a theme uses for a section a new store should not show yet.

  • visibility.devices is a list of "mobile", "tablet" and "desktop": the devices the block shows on. Leave it out to show the block everywhere. Layouts saved before "tablet" existed carry ["mobile", "desktop"] (the old default) or one of the two, so a list never hides a block on a tablet:

    devices Mobile Tablet Desktop
    absent, [], or no known device shown shown shown
    ["mobile", "desktop"], ["mobile", "tablet", "desktop"] shown shown shown
    ["mobile"], ["mobile", "tablet"] shown shown hidden
    ["desktop"], ["tablet", "desktop"] hidden shown shown
    ["tablet"] hidden shown hidden

    A block cannot be hidden on tablets only. The rule is deviceHideValue in @bizzpocket/theme, used by every storefront. The block is still rendered into the page for every shopper; its wrapper gets data-bp-hide with the devices it is hidden on (data-bp-hide="desktop" for ["mobile"]), and the page's CSS hides it at those widths. The page is the same for every shopper (no user-agent check), so it caches. The widths, the same in both storefronts (DEVICE_BREAKPOINTS in @bizzpocket/theme):

    Device Width (CSS px)
    mobile below 768
    tablet 768 to 1023
    desktop 1024 and up

    A hidden-by-device block still fetches its data. For a block that should not exist on a device at all, or for other breakpoints, use media queries in the block's CSS.

  • visibility.abTest names an experiment. The Next.js storefront uses it to pick the block's variant for the shopper; the Bun renderer always shows the default.


The seller's layouts and yours

Your files in layouts/ are defaults. They are copied into the theme's build (dist/blocks.json and dist/templates.json). They are not the store's layouts.

When a shopper opens a page, the storefront picks the layout in this order:

  1. The seller's saved layout for that page, for this store and this theme. (In the seller's preview, their unpublished draft.)
  2. Your default from layouts/<pageType>.json, with your theme's starter content for the store's vertical laid over its props (theme-config.md).
  3. For a commerce page with no default, your home layout. For an optional page with no default, the storefront's own page.

The global layout follows the same order: the seller's saved header and footer, else your global.json.

What this means for you:

  • A saved layout is never changed by a theme update. Once a seller saves the home page, a new block you add to layouts/home.json does not appear on their store. It appears for new stores and for pages the seller never saved. The seller can add your new block from the editor.
  • Saved layouts belong to one theme. If a store switches theme, its saved layouts for the old theme are not used; the new theme's defaults are.
  • Prop changes reach saved blocks only through defaults. A saved block keeps the values the seller set. A field the seller never touched reads your field's default, so changing a default in the block file reaches saved layouts; changing props in layouts/*.json does not.
  • Removing a block or a field is safe. A saved node whose type is gone renders nothing; a saved prop with no field is ignored.

Never rename a block folder

Saved layouts refer to blocks by type, and the type is the folder name. If you rename blocks/featured-collection/ to blocks/product-rail/, every store that saved a layout with a featured-collection node loses that section, without an error.

  • Want a better name in the editor? Change name in block({ ... }). It is only a label.
  • Want a different block? Add a new folder and leave the old one in place.
  • Moving from a 2.x theme? bizzpocket migrate keeps the old types for you with type and variant (migrate.md).

The same holds for field keys: renaming title to heading makes every saved title value disappear. Keep the key and change the field's label.

Next: project-structure.md.