Modules
Building a Web theme
Writing themes for Blesyum Web: package layout, validator, CLI, and the CSP limits of visitor pages.
A Blesyum Web theme renders the visitor-facing side of a site. A package is a ZIP; every file in it is validated before upload.
Fast loop
blesyum-tema init my-theme # copy the starter theme
blesyum-tema validate my-theme # validate (exit code 1 on errors)
blesyum-tema watch my-theme # re-validate on change
blesyum-tema build my-theme -o theme.zipThe validator is byte-for-byte the server's: the CLI does not write its own rules. A package that passes locally passes on upload.
Package layout
theme.json # manifest: name · version · min_engine
templates/ # page skeletons (Liquid)
blocks/<name>/block.json + <name>.liquid
assets/css/…
assets/img/…
locales/en.json- Unknown manifest fields are kept, not stripped (forward compatibility).
block.json'snamemust match its directory: if they diverge the editor lists the block under one name and the engine looks for another, and the block is silently not rendered.- A
min_enginemismatch blocks the upload and the reason is given as a number. Major differences are closed in both directions. - Versions must be full semver:
"1.2"is not1.2.0.
🔴 JavaScript does not run on visitor pages
This is not a missing feature — it is the architecture. Visitor pages are served under a CSP with no script-src and no frame-src; img-src is 'self' data: and form-action is 'self'.
- Don't ship
<script>. It fails silently in the browser:curlshows correct HTML, the endpoint returns 200, logs are clean, and the failure is visible only on the visitor's screen. The validator reports it as an upload-time error. - Don't embed
<iframe>. The box renders empty. Use a link instead — a link is not subject to CSP (CSP restricts resource loading, not navigation). - Don't pull images or fonts from a CDN. Put assets in
assets/. - Don't submit forms with
fetch. Use a plainPOST.
Why: theme code is written by the tenant or their agency, and the panel lives on a separate origin (<slug>--panel.web.<domain>). Theme JS on the same origin could read the panel's session token, and no CSP could stop that.
What the validator checks
Syntax · CSP (<script>, external img/font, <iframe>) · accessibility (missing alt, heading order) · performance (unsized images, oversized assets) · locales (a missing translation is a warning, not an error — the last link of the chain is the source string).
Uploads and versions
Every upload is a separate record; the same name + version cannot be installed twice. Uploading is not activation: repainting a live site without asking would apply a decision the customer never made. Activation is a separate step and produces a compatibility report (blocks with no counterpart, migrated settings).
Rolling back needs no separate mechanism: the previous version's record is still there and can be activated. The site's theme history shows which one is live.