Skip to content
14-day free trial, no card9 languages176 business types · 50 apps
EN· USD
Try a live demoStart free trial

Page-builder blocks

How pages are stored as block JSON, which block types exist, and what adding a new block involves (a core change, not a plugin).

  • about 9 min

Every website page is a stack of blocks saved as JSON on the page translation (blocks Json // Block[]). src/components/blocks/BlockRenderer.tsx paints them; the visual builder (/admin/pages/[id], /admin/design/layouts) edits them on a live same-origin canvas. There are 33 block types today, grouped as hero, content, proof, commerce, blog, contact and layout — from hero, features, faq, pricing and cta to the system blocks productGrid, blogList, cartSummary and checkoutForm, plus marketWidget (“Marketplace widget”), which paints a widget installed from the marketplace.

Two blocks as stored
[
  {
    "type": "hero",
    "eyebrow": "Dubai's trusted fit-out partner",
    "heading": "Beautiful spaces, built right.",
    "primaryCta": { "label": "Get a free quote", "href": "/quote" },
    "secondaryCta": { "label": "WhatsApp us", "href": "whatsapp" },
    "variant": "split"
  },
  {
    "type": "faq",
    "heading": "Questions",
    "category": "general",
    "limit": 6,
    "columns": 2,
    "hidden": false
  }
]
  • Shared flags (BlockBase): hidden keeps a block in the JSON without painting it; id is the builder's stable id (ignored by the public renderer).
  • A CTA href of whatsapp opens WhatsApp with a greeting; tel calls.
  • System layouts (blog home, post, shop, product, cart, checkout) are reserved pages whose blocks wrap the dynamic core.
Plugins cannot add page-builder block types (the plugin guide lists this as not supported); a new block type is a core module change. To offer a website section to other workspaces without a core change, publish a marketplace widget (next lesson): owners add it through the marketWidget block.

What a new block type involves (core change)

  1. Add an interface XBlock extends BlockBase { type: "x"; … } and add it to the Block union in src/lib/blocks/types.ts.

  2. Add a BLOCK_CATALOG entry: type, label, description, group and defaults (what the builder inserts).

  3. Add a component and a case "x" in paint() of src/components/blocks/BlockRenderer.tsx.

  4. Ship it through the built-in module pipeline: export the owning module zip (npm run module:pack <id>[/<sub>]), edit, import & rebuild.

Written from: src/lib/blocks/types.ts, src/lib/blocks/README-builder.md, src/components/blocks/BlockRenderer.tsx, docs/PLUGIN-DEVELOPER-GUIDE.md, docs/MODULES.md, src/lib/help/articles.ts, docs/DEVELOPERS/WIDGET-SPEC.md