App blocks

An app block is a piece of storefront markup your app ships in a release. Merchants add it in the theme editor to a section that accepts app blocks, on the pages the block lists, and set its settings there. A block runs in one of two modes: template blocks are rendered into the page itself, with no frame; hosted_surface blocks render their markup and then open one of your hosted surfaces in a frame for interactive UI.

A template block is cached with the page and shown to every shopper, so it reads only public page data: never the cart or the customer. If what you show depends on the shopper, use a hosted surface.

A block keeps its mode for good. A release that gives an existing key the other mode is refused (block "…" is template in the current release and cannot become hosted_surface; declare the hosted_surface version under a new key), because merchants placed that block as it was. Declare a new key for the new mode. A key you remove from a release is retired and cannot be used again.

Blocks are listed under storefront_blocks in tringify.app.json, or in the Developer Portal under the app's configuration. In tringify.app.json each block names its Vascula file in source_file; the CLI reads it in when you push. The Developer API carries the same file inline as source.

An app can declare up to 10 blocks. Every problem is reported with the block's key and what to change, both when you push the configuration and when you create a release.

These seven are the only page types an app block can be placed on, and the list doesn't grow with your app. Search results, category, brand and vendor pages, the wishlist, sign-in pages and the 404 page don't take app blocks, and neither do the header and footer every page shares. For something that must show on every page, use an app embed.

A block that reads product must list exactly ["product"], and one that reads collection exactly ["collection"]: those pages are the only ones that have that data. The theme editor, the Store API (GET /storefronts/{storefront_id}/app-blocks) and the MCP tool list_app_blocks offer a block only on its pages, and any save that places it on another template is refused with the block's name. Other templates (search, sign-in, the header and footer sections shared by every page) take no app blocks.

Inside a page, a block can go only in a section whose blocks slot sets accept_app_blocks in its schema. Which sections those are is up to the theme; see Theme blocks.

Declare the ctx roots the block uses in ctx_needs, as a theme section does; see the CTX reference. A block that declares a root its mode cannot read is refused when you push it.

Settings work as in theme blocks: the merchant's values arrive as settings.<id>. Format prices with the money filter, and split a price into payments with money_split; never do arithmetic on money in the markup.

App markup is placed in a merchant's page without a frame, so it is held to one allowlist, the same for app blocks, Vascula app embeds and surface posters. It allows reading markup and links only. The source is checked when you push it; each rendered block is checked again before it reaches the page, and a block whose output breaks the rules or is larger than 32 KB is left out of that page.

Style blocks with the platform's tf-ab-* classes. They use only currentColor, em sizes and the inherited font, so a block takes the font and colours of whatever theme it sits in. The storefront adds their stylesheet once on any page that shows a template block.

The storefront wraps every block in an element of its own, and headings and paragraphs inside a block have no outer margin, so space it with tf-ab-stack and tf-ab-gap-*.

Rendering is also bounded per block and per page. A block that runs over is left out of the page; the rest of the page renders as usual.

Template blocks are part of the page: they are rendered with it and cached with it at the edge, so they cost nothing per visit. A page refreshes when the store's content changes (a product's price, for example) and when the merchant publishes theme changes, so a block reading product.price always shows the current price. A store gets new block markup when it installs or updates to the release that contains it.

If a block cannot be shown (the app was uninstalled, or the installed release no longer has the block), the page renders without it. A hosted_surface block's frame loads after the page, from your server.

This block shows "or 3 payments of …" under the product price. Its source is blocks/instalments.vasc; the merchant chooses the number of payments and whether to show a badge. money_split divides the current price into payments that add up to it exactly in the currency's minor units; the first payment carries any remainder, so it is the one to show.

Because it reads product, the block lists only product in pages. It renders into the page with the theme's font and colours, follows the selected variant's price when the product section re-renders, and is cached with the product page. tringify app init starts a new project with this block.