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.filtersascategory, so a listing block can scope itself by the path. checkoutis owned by the storefront. Every store gets the same checkout page. Do not ship acheckout.json.- Account pages.
/account,/account/ordersand/account/wishlistshow the storefront's own page inside your header and footer. Youraccount,orders,order_detailandwishlistlayouts 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/blogreturns 404). bizzpocket devserves every URL in the table except/checkout, the old URLs too (it serves them in place instead of redirecting). Every other URL gets thenot_foundpage. The shopper's own pages (account,orders,order_*,login,signup) are never cached. Underdev --mockthere is no signed-in shopper: their layouts render, and blocks that ask for the shopper's data getnull(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):
{
"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, orhiddenin aschemaVersion: 1file:INVALID_MANIFEST(troubleshooting.md); - bad JSON:
INVALID_LAYOUT_JSON; - a node whose
typenames 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
pageTypethat 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:
{
"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:
{
"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: trueremoves 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.devicesis 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:devicesMobile Tablet Desktop absent, [], or no known deviceshown 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
deviceHideValuein@bizzpocket/theme, used by every storefront. The block is still rendered into the page for every shopper; its wrapper getsdata-bp-hidewith 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_BREAKPOINTSin@bizzpocket/theme):Device Width (CSS px) mobilebelow 768 tablet768 to 1023 desktop1024 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.abTestnames 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:
- The seller's saved layout for that page, for this store and this theme. (In the seller's preview, their unpublished draft.)
- Your default from
layouts/<pageType>.json, with your theme's starter content for the store's vertical laid over its props (theme-config.md). - For a commerce page with no default, your
homelayout. 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.jsondoes 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 adefaultin the block file reaches saved layouts; changingpropsinlayouts/*.jsondoes not. - Removing a block or a field is safe. A saved node whose
typeis 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
nameinblock({ ... }). 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 migratekeeps the old types for you withtypeandvariant(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.