Limits and security
On this page
A theme runs on every store that installs it and is seen by every shopper, so the platform does not trust it with more than it needs. This page explains the security model in plain terms, and the limits you will meet while building: what is cleaned for you, what you must check yourself, what data a theme can reach, how caching and cookies work, the content security policy, and the timeouts and caps.
The full list of numbers is in the limits reference.
The model in one paragraph: a theme renders data, it does not hold secrets or power. Seller input is
cleaned before your render sees it. Data comes only through a fixed set of read-only storefront
operations, scoped to the store being shown. Pages are the same for every shopper, so they can be
cached. Only scripts the storefront itself wrote may run, and shopper sessions live in cookies a theme
cannot read.
Rich text is sanitised
An f.richText() value is HTML written by a seller. Before your render sees it, the SDK rebuilds it
from an allowlist, so you can put it in the page with dangerouslySetInnerHTML:
<div className="rt" dangerouslySetInnerHTML={{ __html: p.body }} />What the sanitiser keeps:
| Kept | How |
|---|---|
p, br, strong, em, b, i, u, s, span, small, sup, sub, code, pre, hr, blockquote |
as bare tags, with no attributes |
h2 to h6 |
bare. There is no h1: the page has one already. |
ul, ol, li |
bare |
table, caption, thead, tbody, tfoot, tr |
bare |
th, td |
with colspan / rowspan only, as whole numbers from 1 to 1000 |
a |
with href only when it is a safe URL, and target="_blank", which always gets rel="noopener noreferrer" |
What it removes:
- every attribute not listed above:
style,class,id,onclickand every other event handler; script,style,iframe,object,template,noscriptandtextarea, with everything inside them;- every other tag (
div,img,h1,form...). The tag goes, its text stays; - comments,
<![CDATA[...]]>and doctype-like tags; - nesting deeper than 256 open tags (the tags go, the text stays).
Text is escaped, and every open tag is closed at the end. A value longer than 200,000 characters (or the
field's maxLength) is replaced by the field's default as a whole, never cut in the middle of a tag.
Warning. Only fields are cleaned. HTML that comes from data is not: a product's descriptionHtml, a
page body from gql(). Run it through sanitizeRichText() from @bizzpocket/theme before you inject
it: dangerouslySetInnerHTML={{ __html: sanitizeRichText(item.descriptionHtml) }}. It applies the same
allowlist, so pictures and divs in that HTML are unwrapped.
Style the result through your own wrapper class (.rt p, .rt a), since the tags carry none.
Safe URLs
A link or picture URL can carry an attack (javascript:alert(1)) or send the shopper to another site
(//evil.example). The SDK has two rules:
| Rule | Allows | Used for |
|---|---|---|
isSafeUrl(url) |
a path that starts with one / (/shop), a #anchor, and https:, mailto: and tel: URLs |
links (href) |
isSafeMediaUrl(url) |
a path that starts with one /, and https: URLs |
pictures and videos (src) |
Both refuse //host and /\host (browsers read them as another site), plain http:, data:,
javascript:, and any URL with a control character in it (browsers strip tabs and newlines, so
/\t/evil.example would become //evil.example).
Where they are applied for you:
f.link()values are checked withisSafeUrl, andf.image()/f.video()values withisSafeMediaUrl. An unsafe value becomes the field's default.<Link href>drops an unsafehref(the text stays, the link goes).<Image src>renders nothing for an unsafesrc.- Links inside rich text are checked with
isSafeUrl.
Where you check them yourself: URLs from data, such as a category's href, a social link or a menu
item. Use toSafeUrl(value), which returns the trimmed URL or null, before you put it in a plain
<a> or <img>. data.md shows the helpers.
Island props
An island's props travel from the server to the browser inside the page's HTML, as JSON in the
island's data-props attribute. That has three consequences.
- Props are public. Anyone can read them with "View source". Pass only what the shopper may see. Never pass a token, a key, a cost price or another shopper's data.
- Props must be JSON. A prop may be a string, a number, a boolean,
null, an array or a plain object. A function, a class instance, aDate, aMapor a JSX element is not data: the build stops withNON_SERIALIZABLE_ISLAND_PROPwhen it can see one. Anything it cannot see is dropped at render time (functions, symbols,bigints and React elements), andundefineddisappears. Turn aDateinto a string yourself. - Props make the page heavier. Every byte is in the HTML of every page that shows the block. Pass the fields the island uses, not whole product objects.
Islands also get no JSX children, see no React context from the page, and can import neither
@bizzpocket/theme-sdk nor zod (CLIENT_IMPORT_FORBIDDEN). The rules are in
interactivity.md. The browser loads an island's code only from a path on
the storefront's own address, the one the server wrote.
What data a theme can reach
A theme never talks to a database or an admin API. It reads data through storefront operations, and which ones depends on where the code runs.
| Where | How | Operations |
|---|---|---|
data() |
the data helpers | products, product, related, categories, menu, store, home, search, and gql(document) |
load() |
ctx.query(op, vars) |
the 13 public operations below, plus 5 shopper ones: customerMe, customerOrders, customerOrderDetail, customerSavedAddresses, customerWishlist |
| an island | useQuery(op, vars) |
the 13 public operations below only |
The public operations (BROWSER_QUERY_OPS in @bizzpocket/theme/client):
productGridProducts, productSearch, productDetail, productSuggestions, productFrames,
categoryTree, categoryTreeWithFeatured, categoryFilters, navigationMenu, storeProfile,
storeHome, storePromotions and gemCertificate.
Rules that hold everywhere:
- Read only. Every operation is a query. A theme changes nothing on the server: cart and account changes go through SIR events, which the storefront host carries out.
- One store. The store is the one being shown. A
storeSlugyou pass touseQueryis replaced by the current store's. - Public or as the shopper. On the Bun storefront,
load()and runtimedata()send the public operations (catalogue, store, menus, promotions) without the shopper's cookie: their answer is the same for everyone, so the page stays cacheable. Thecustomer*operations, and agql()document with any top-level field outside the public list, run with the shopper's own cookie and make the page personal.useQueryruns with the shopper's cookie. - Account data never reaches the browser by query.
useQueryrefuses everycustomer*operation (404 NOT_FOUND). Read the shopper inload(), or useuseCustomer()anduseWishlist(). load()has a typed list. An operation outside it is a type error, and an unknown name resolves tonullat run time.gql()is a query you type yourself. Nothing checks it against the schema at build time. With a developer token (inbizzpocket dev --store), agql()document must be a query whose top-level fields are all in the public list above, with no fragments at the top level, and naming no other store. Anything else is refused and the need isnull. Agql()need is resolved with the page's other data; in aruntimeblock only the Bun storefront runs it. Keepgql()blocksstatic.
Developer-token scope
bizzpocket dev --store <slug> uses a developer token (bpdt_...) made by the store owner. It is
deliberately small:
- it reads the public data of one store, the one it was made for;
- only the public operations above, and the page endpoint
devrenders through; - never customers, orders, carts, checkout or wishlists, never drafts, never a write;
- at most 120 requests a minute (past that,
429), and at most 32 operations in one page call; - it expires (7, 30, 90 days or 1 year), and the owner can revoke it at once.
It lives in your shell as BIZZPOCKET_DEV_TOKEN, never in the theme. Creating, rotating and revoking
it are in tokens.md.
Caching and cookies
The storefront caches page HTML and shares it between shoppers. This is why a theme must keep personal data out of the server HTML. On the Bun storefront the rules are:
| Page | cache-control |
|---|---|
a normal page, including one whose load(), runtime blocks or local fallback use only public operations |
public, s-maxage=60, stale-while-revalidate=600 (shared caches keep it 60 s, and may serve it stale for 10 minutes while they refresh it), vary: accept-encoding: the same HTML for every shopper |
a page where load(), a runtime block or a local fallback ran a customer* operation (or a gql() document that is not all public), with or without a cookie; and account, order, login and signup pages |
private, no-store, vary: cookie |
a preview (?bizz_preview=), a degraded page, or a page whose data did not finish in time |
no-store |
/_bp/q/<op> (useQuery), with or without a cookie |
public, max-age=30, stale-while-revalidate=60, vary: accept-encoding (the shopper's session is never forwarded, so the answer is the same for everyone; errors are no-store) |
| theme JavaScript and CSS | public, max-age=31536000, immutable (file names carry a content hash) |
"Degraded" means some data failed or timed out, so the page shows less than it should. It is sent but never cached, so the next shopper gets a fresh try.
What it means for you:
- Personal data belongs in the browser, through the hooks. A
load()that reads only public operations keeps the page cached. A shopper-scoped call (acustomer*operation, or agql()document that is not all public) makes the pageprivate, no-storefor every request, guests included. Use one only when nothing else works. - Keep no state between requests. Page HTML must come only from the block's props and the
ctx.queryanswers of the current request.load()andrendermust not keep anything at module level, such as a cache of query results. AcustomerMeanswer kept in module scope would be rendered into a later page that uses only public operations, and that page is cached publicly. - Do not read or write cookies from a theme. The shopper's session is in
customer_session, anhttpOnlycookie your code cannot read, and it is set only for the store's own address. UseuseCustomer()to know who is signed in. - Do not put shopper data in the URL. URLs are logged and cached. The host's own order tracking, for example, sends the phone number in a POST body, never in the URL.
Content security policy
Every storefront page carries a content security policy (CSP). On the Bun storefront it is:
style-src 'self' 'unsafe-inline'; script-src 'self' 'nonce-<random>' 'strict-dynamic'; object-src 'none'; base-uri 'none'The production storefront sends the same style-src and script-src (plus 'wasm-unsafe-eval' when
its captcha is turned on). The nonce is new for every
response, and the storefront puts it on the scripts it writes itself (the island loader, React and the
SIR runtime). Scripts those load may run ('strict-dynamic'). Nothing else may.
So, in a theme:
| Works | Is blocked |
|---|---|
| islands, and the npm packages bundled into them | a <script> you write in a block, inline or with src |
sir.* attributes |
inline event attributes in HTML (onclick="...") |
React onClick and friends, inside an island |
a third-party script tag (analytics, chat widgets, pixels) |
<script type="application/json"> data, such as sir.variantData() (it is data, not code) |
<object> and <embed> |
inline style attributes and <style> |
a <base> tag |
Third-party tags such as analytics are the storefront host's job: it loads its own, with its own nonce. A theme cannot add one.
Timeouts and caps
The ones you are most likely to meet. The limits reference has the full table.
| What | Limit | What happens past it |
|---|---|---|
load() on the Bun storefront |
3 s | the block renders with {}, the page is degraded |
| the whole page render on the Bun storefront | 8 s | missing data becomes null, the page is degraded |
| one storefront operation from the Bun storefront | 5 s | that need is null |
| one operation in the page endpoint | 3 s | that need is null |
| waiting for the last data before the headers | 400 ms after the first HTML is ready | the page is sent no-store instead of cacheable |
useCartActions() / addToCart() |
15 s | the Promise rejects with TIMEOUT |
useQuery variables |
4 KB of JSON | 413 VARS_TOO_LARGE; the hook says so without sending |
useQuery cache in the browser |
100 answers per tab | the oldest is forgotten |
f.richText() value |
200,000 characters (or maxLength) |
the field's default is used |
f.products() / f.categories() |
50 items (or max) |
the rest are dropped |
f.blocks() children |
24 (or max) |
the rest are not rendered |
| containers inside containers | 3 levels | deeper children are not rendered |
page.route.q (search text) |
200 characters | cut |
page.route.filters |
16 keys; names start with a letter (up to 40 characters); values up to 200 characters | the rest are dropped |
page.route.page |
up to 6 digits | ignored |
page.route.sort |
letters, digits, _ : . -, up to 40 characters |
ignored |
| a URL handle | letters, digits, _ and -, up to 200 characters |
404 |
| global + block CSS inlined in a page (Bun storefront) | 14 KB gzip | the CSS is linked as a file instead |
| CDN picture width | 1600 px, on the ladder 160 to 1600 |
rounded up to a rung (308 redirect), never larger |
| developer token | 120 requests a minute, 32 operations a page | 429, or the need is null |
| newsletter sign-ups, sign-in and sign-up | rate limited per store and address (sign-in: 5 tries per 15 minutes) | 429 / RATE_LIMITED, see forms.md |
On the Bun storefront, a block that throws while it renders becomes an empty
<section data-bp-error>. The rest of the page renders, and no error text reaches the shopper.
Next: migrate.md.