Skip to main content

Extending the Page Builder

The CMS module ships built-in components — Row, Columns, Text, Heading, Button, InsertBlock, and others — but every other backend module can contribute its own components. (InsertTemplate remains registered for legacy content trees but is no longer listed in the drawer palette.) The cms, catalog, blog, newsletter, orders, invoices and transactional_emails modules already declare their blocks this way. Their renderers are still the built-in ones in @endora-commerce/cms-components and @endora-commerce/email-components; a module package outside the platform ships its own, as section 2 describes. A contributing module participates in two places:

  1. Manifest declaration: declare the block's metadata — name, labels, palette category, contexts and editable fields — in the module's own manifest.ts. The CMS module builds its Page Builder registry from the manifests of the composed modules, so there is no registration call to write.
  2. Renderers: ship, in the module's own package, the code that draws the block on the storefront, in e-mail and in the admin editors.

1. Declare the block in the manifest​

Add blocks and blockCategories to your module manifest:

// the promotions module: src/manifest.ts
import { defineModuleManifest } from '@endora-commerce/contracts';

export const manifest = defineModuleManifest({
id: 'promotions',
// ...name, version, dependencies...
blocks: [
{
name: 'promotions.PromoBanner',
labelKey: 'blocks.promoBanner.label',
descriptionKey: 'blocks.promoBanner.description',
category: 'promotions',
/** Omit email/invoice — this component is storefront-only. */
contexts: ['cms'],
fields: {
headline: { type: 'text', label: 'Headline', required: true },
codeInput: { type: 'text', label: 'Promo code' },
tone: {
type: 'select',
label: 'Tone',
options: [
{ label: 'Info', value: 'info' },
{ label: 'Urgent', value: 'urgent' },
],
},
},
previewIcon: 'ticket',
weight: 10,
},
],
blockCategories: [
{ key: 'promotions', titleKey: 'blocks.category.promotions', contexts: ['cms'] },
],
});

The schema is BlockDefinitionSchema and BlockCategorySchema in packages/contracts/src/cms.ts (both exported from @endora-commerce/contracts). defineModuleManifest refuses a manifest that breaks either of two rules:

  • A block name is <module id>.<PascalCaseName>, and the part before the dot must be the declaring module's own id. The name is written into the stored page content and never rewritten, so choose it once.
  • A block's category must be declared in the same manifest's blockCategories for every context the block lists. Several modules may declare the same category key; the palette merges them.

labelKey, descriptionKey and titleKey are relative to the declaring module's own i18n bundle (blocks.promoBanner.label, not promotions.blocks.promoBanner.label). Nothing can check that when the manifest is defined, so get it right by hand.

Field types are taken from the closed enum declared in packages/contracts/src/cms.ts: text | textarea | number | select | radio | array | object | external | uuid | richtext. This metadata is React-free; the backend never imports a renderer.

A block is offered only while its module is present: the registry filters declarations by module presence when it answers GET /api/v1/admin/cms/page-builder/config, so a module that is switched off takes its blocks out of the palette with it.

Translatable texts (translatable)​

The Page Builder's Translate action sends a block's texts to a language model only when the block says which of its props are prose. Declare it beside fields:

{
name: 'promotions.PromoBanner',
// ...
translatable: [
{ path: 'headline' },
{ path: 'items[].title' },
{ path: 'body', format: 'tiptap' },
],
}
  • path is a prop name, or names joined by .; name[] means "every element of this array". A value that is not a string at the path is skipped.
  • format is plain (the default), tiptap for a prop holding a TipTap JSON document, or html for an HTML string. Formatting and link targets never reach the model: rich text travels with numbered tags, HTML tags as ordered placeholders.
  • Declare only prose a shopper reads. Never declare a URL, slug, id, code, colour, icon name, asset reference, HTML or script source, editorName, or a derived HTML prop beside a TipTap one — the block's own resolveData regenerates that after translation.
  • Do not declare slot props: the blocks nested in a slot declare their own.
  • translatable: [] says the block has no prose. A block with no translatable at all is left untouched and reported to the editor as "cannot be translated" — so an undeclared block is never sent anywhere.

2. Ship the renderers​

A module package draws its own blocks. It does so through up to three layers, one per process that renders a block, plus an optional stylesheet. Each is a subpath of the package's exports map, and each is optional: a module whose blocks are e-mail-only ships the e-mail layer and nothing else.

SubpathWhat it exportsWho renders with it
./storefrontcontributions — React renderers for the module's cms blocksthe storefront, in the server-rendered HTML
./emailemailBlocks — pure functions that render the module's email blocks to HTML and textthe backend when it sends, and the admin's e-mail editor
./admincontributions.blocks — editor renderers, beside the module's routes and zonesthe admin's CMS and e-mail editors
./blocks.cssone finished stylesheetthe storefront and the admin editor

This is for a module package — one a storefront and an instance install from a registry. The platform's own modules do not ship these layers yet: their package.json is generated, and the generator does not render the three subpaths. An overlay module has no package; its blocks are covered under A block no package renders.

The examples below quote the platform's own acceptance fixture: a module outside every platform package that ships all three layers and a stylesheet for one block, acceptance_blocks.Badge.

The package​

A surface finds the package by its own package.json:

"files": [
"dist",
"i18n",
"blocks.css",
"tailwind.css"
],
"endora": {
"type": "module",
"id": "acceptance_blocks"
},
"exports": {
".": {
"types": "./dist/manifest.d.ts",
"default": "./dist/manifest.js"
},
"./backend": {
"types": "./dist/backend/index.d.ts",
"default": "./dist/backend/index.js"
},
"./admin": {
"types": "./dist/admin/index.d.ts",
"default": "./dist/admin/index.js"
},
"./storefront": {
"types": "./dist/storefront/index.d.ts",
"default": "./dist/storefront/index.js"
},
"./email": {
"types": "./dist/email/index.d.ts",
"default": "./dist/email/index.js"
},
"./blocks.css": "./blocks.css",
"./tailwind.css": "./tailwind.css",
"./i18n/*": "./i18n/*",
"./package.json": "./package.json"
  • endora.type must be module, and endora.id the module id that prefixes its block names. A package without that block is not a module package: blocks:generate says so in a note and registers nothing from it, and its blocks render as placeholders.
  • files lists everything an exports entry points at — blocks.css and tailwind.css beside dist. An entry whose file is not in the tarball is refused by the generator that would import it.
  • Each layer publishes type declarations beside its JavaScript (the types condition above). A storefront written in TypeScript imports ./storefront from its generated registry, and blocks:generate refuses a storefront layer that ships none as untyped-layer.
  • A package with ./admin also publishes ./tailwind.css, which tells the admin's Tailwind build where the layer is. endora generate refuses an admin layer without it. The fixture's is one line, quoted below the list.
  • The layers' imports are peer dependencies: @endora-commerce/contracts, @endora-commerce/page-builder-core, @endora-commerce/email-components, @puckeditor/core and react, with @endora-commerce/platform for the backend.
  • The build is plain tsc, which keeps a leading 'use client' and emits the declarations. Relative imports are written with the .js extension.
@source "./dist/admin";

Where the names in the examples come from:

NameImport it from
StorefrontContributions, PageBuilderBlockEditorConfig, useBlockRenderEnvironment@endora-commerce/page-builder-core/contributions
sanitizeRichHtml@endora-commerce/cms-components
EmailBlockRenderers@endora-commerce/email-components/render/block-renderers
escapeHtml, escapeAttr@endora-commerce/email-components/render/escape-html
AdminContributions, EmailBlockRendererRegistryPort@endora-commerce/contracts
ModuleContext, lazyPort@endora-commerce/platform/kernel

The declaration the layers draw​

The block is declared in the module's manifest, for both contexts it is drawn in, in a palette section the same manifest declares for both:

blockCategories: [
{ key: 'acceptance', titleKey: 'blocks.section', contexts: ['cms', 'email'], weight: 900 },
],
blocks: [
{
// The persisted name — `<endora.id>.<Name>`, and permanent. Written as a
// literal: `endora check` reads a block's name and contexts off the
// manifest's text, and a name it cannot read is one it cannot hold a
// renderer to.
name: 'acceptance_blocks.Badge',
labelKey: 'blocks.badge.label',
descriptionKey: 'blocks.badge.description',
category: 'acceptance',
contexts: ['cms', 'email'],
fields: {
text: { type: 'text', label: 'Text' },
// Forces every renderer of this block to throw. It exists for the
// failure-isolation assertion and for nothing an operator would use.
explode: {
type: 'radio',
label: 'Fail on render',
options: [
{ label: 'No', value: 'no' },
{ label: 'Yes', value: 'yes' },
],
},
},
defaultProps: { text: 'New badge', explode: 'no' },
weight: 10,
},
],

Every renderer is keyed by the block's full name, and a package renders only the blocks its own manifest declares, for a context that block declares: cms for the storefront and the CMS editor, email for e-mail. Write the name and the contexts as literals, in the manifest and in each layer: check:block-renderers reads them off the source text, and a name it cannot read is one it cannot hold a renderer to. A computed renderer key escapes the check and is refused when the surface composes it.

The storefront layer​

src/storefront/index.ts exports contributions, a map from block name to a Puck component config:

import type { StorefrontContributions } from '@endora-commerce/page-builder-core/contributions';

import { Badge } from './Badge.js';

export const contributions: StorefrontContributions = {
blocks: {
'acceptance_blocks.Badge': {
defaultProps: { text: 'New badge', explode: 'no' },
render: Badge,
},
},
};

The renderer is an ordinary React component. Its props are the block's stored props, with the defaultProps above filled in underneath them — so a prop the module added after a page was saved still has a value:

'use client';

import { useBlockRenderEnvironment } from '@endora-commerce/page-builder-core/contributions';
import type { ReactNode } from 'react';

export interface BadgeProps {
readonly text?: string;
readonly explode?: string | boolean;
}

/**
* The renderer's one built-in string — a label that is not operator content —
* shipped in both languages inside the layer and chosen by the request's
* content language, with English as the fallback. The storefront's own
* catalogue belongs to the storefront's owner.
*/
const LABEL: Readonly<Record<string, string>> = { en: 'Badge', pl: 'Odznaka' };

/**
* Synchronous, reads no browser global, and draws the same output on the
* server and on hydration for the same props: it is part of the
* server-rendered HTML.
*/
export function Badge({ text, explode }: BadgeProps): ReactNode {
const { language } = useBlockRenderEnvironment();
if (explode === true || explode === 'yes') {
throw new Error('acceptance_blocks.Badge was asked to fail on render');
}
const label = LABEL[language.slice(0, 2).toLowerCase()] ?? LABEL['en'];
return (
<span className="acceptance_blocks-badge" title={label}>
{`acceptance-badge:${String(text ?? '')}`}
</span>
);
}

A storefront renderer runs once on the server and once in the browser, so:

  • it is synchronous — no async component — and reads no browser global (window, document, localStorage) while rendering, only in an effect;
  • it draws the same output on the server and in the browser for the same props: no Date.now(), no Math.random(), no locale-dependent formatting without the language from useBlockRenderEnvironment();
  • every file of the layer starts with 'use client'. check:block-renderers does not hold this one; a layer without it fails the storefront's build;
  • it imports only react, react-dom, @puckeditor/core, @endora-commerce/page-builder-core, @endora-commerce/cms-components, @endora-commerce/contracts and its own files. Nothing server-only, no admin kit, no platform, no other module. Data it needs comes from its props, from the CMS render context, or from a fetch in an effect;
  • block props are untrusted input: HTML is injected only as dangerouslySetInnerHTML={{ __html: sanitizeRichHtml(value) }};
  • a label the renderer prints itself — one that is not the operator's content — ships in English and Polish inside the layer and is chosen by useBlockRenderEnvironment().language, with English as the fallback.

Installing it in a storefront. A storefront owner adds the package to their storefront (pnpm add) and builds. blocks:generate, which the dev and build scripts of a storefront created by release 0.103.0 or later run, finds every installed module package that declares ./storefront or ./blocks.css and writes the registry and the stylesheet import — there is no line to add to any file.

A storefront created by an earlier release has none of this, and upgrading does not add it. An upgrade moves a storefront's packages and leaves its source as it was written, so such a storefront has no blocks:generate script, no lib/page-builder/ and no presence rule: a package's storefront layer is not rendered there, and neither A block no package renders nor the storefront row of When the module is switched off below applies to it, until its owner brings the files over by hand. The steps are in the Upgrading an instance guide, under Module blocks in an existing storefront.

When endora install writes an instance and a storefront in one run, it adds the instance's modules that publish a storefront layer to the storefront's dependencies, once. No platform module publishes one yet, so a default install adds nothing; a package added to the instance afterwards is added to the storefront by its owner.

What blocks:generate refuses, writing nothing and exiting 1:

RefusalMeaning
untyped-layerthe package publishes ./storefront with no type declarations
missing-layer-filean exports entry points at a file the package does not hold
layer-without-subpaththe package ships src/storefront/index.ts and declares no ./storefront
duplicate-moduletwo installed packages declare the same module id

A block no package renders​

A storefront can also render a block itself — typically one an overlay module of its own instance declares — by adding it to lib/page-builder/local-blocks.tsx, the one file of the block registry that is the storefront owner's. A local block never replaces a block a package or the platform already renders.

The e-mail layer​

src/email/index.ts exports emailBlocks. Each renderer is a pure function — no React, no I/O — that returns rows of the e-mail's table layout and escapes every prop:

import type { EmailBlockRenderers } from '@endora-commerce/email-components/render/block-renderers';
import { escapeHtml } from '@endora-commerce/email-components/render/escape-html';

interface BadgeProps {
readonly text?: string;
readonly explode?: string | boolean;
}

function assertRenderable(props: BadgeProps): void {
if (props.explode === true || props.explode === 'yes') {
throw new Error('acceptance_blocks.Badge was asked to fail on render');
}
}

export const emailBlocks: EmailBlockRenderers = {
'acceptance_blocks.Badge': {
defaultProps: { text: 'New badge' },
html: (props: BadgeProps, ctx) => {
assertRenderable(props);
return (
'<tr><td style="padding:8px 24px;font-family:Arial,Helvetica,sans-serif;">' +
`<span style="display:inline-block;padding:4px 10px;border-radius:6px;background-color:${ctx.accentColor};color:#ffffff;font-size:14px;font-weight:bold;">` +
`acceptance-badge:${escapeHtml(String(props.text ?? ''))}` +
'</span></td></tr>'
);
},
text: (props: BadgeProps) => {
assertRenderable(props);
return `acceptance-badge:${String(props.text ?? '')}\n`;
},
},
};

text is optional; without it the plain-text part is derived from the HTML. The second argument carries accentColor, the message's language — a label the renderer prints itself follows it, as on the storefront — and renderSlot(nodes), which renders nested content with the platform's own renderer. {{var …}} directives in the output are resolved afterwards, exactly as in a built-in block. The layer imports only @endora-commerce/email-components/render/*, @endora-commerce/contracts and its own files, because the same function runs in the backend and in the admin's browser.

The module's backend registers the renderers when the platform boots, and its manifest names email in dependencies:

// `email` owns the registry this module registers its e-mail renderer into.
// It is non-deactivatable, so the edge never fails closed.
dependencies: ['email'],
import type { EmailBlockRendererRegistryPort } from '@endora-commerce/contracts';
import { lazyPort, type ModuleContext } from '@endora-commerce/platform/kernel';

import { emailBlocks } from '../email/index.js';

/** This module persists nothing. */
export const entities = [] as const;

export function registerModule(ctx: ModuleContext): void {
// From a boot hook, unprobed: the registry is ungated and decides presence
// itself, per render, on the contributor recorded here — so switching this
// module off, or back on, needs no restart and no re-registration.
ctx.onBoot(() => {
lazyPort<EmailBlockRendererRegistryPort>(ctx, 'emailBlockRendererRegistry').register(
'acceptance_blocks',
emailBlocks,
);
});
}

register never throws. A name the module does not own, or an entry without an html function, is refused with a warning in the backend log and listed in the refused array the call returns — assert on that array in a test.

Transactional e-mail and newsletter campaigns both render through that registry, and content holding the block can be saved in either. A built-in e-mail block cannot be overridden: a contributed renderer is consulted only for a name the platform does not draw itself.

The admin layer​

The module's ./admin layer — the one that already declares its routes and zone contributions — lists an editor renderer per block and editor:

import type { AdminContributions } from '@endora-commerce/contracts';

export const contributions: AdminContributions = {
blocks: [
{
name: 'acceptance_blocks.Badge',
context: 'cms',
component: () => import('./badge-editor.js'),
},
{
name: 'acceptance_blocks.Badge',
context: 'email',
component: () => import('./badge-email.js'),
},
],
};

For the CMS editor the default export is the block's renderer — usually the storefront's own component, so the canvas shows what the storefront draws:

import type { PageBuilderBlockEditorConfig } from '@endora-commerce/page-builder-core/contributions';

import { Badge } from '../storefront/Badge.js';

const editor: PageBuilderBlockEditorConfig = { render: Badge };

export default editor;

For the e-mail editor it is the e-mail layer's renderer, the function the send path runs, so the canvas and the preview cannot differ from the message:

import { emailBlocks } from '../email/index.js';

export default emailBlocks['acceptance_blocks.Badge'];

The block's label, palette section, default props and field set come from the manifest declaration, not from the contribution. A CMS editor config may carry fields to replace the editor of a field the manifest declares — a picker in place of a text input — and cannot add a field the manifest does not declare.

A declared block with no editor renderer is still insertable and editable: the editor builds its fields from the manifest declaration and shows a neutral preview that names the block. That is what an overlay module's block gets, since an overlay module has no admin layer. In the e-mail editor such a block is also absent from the HTML preview, although the backend renders it in the message that is sent.

Installing it in an instance. The instance's owner adds the package to the instance's dependencies and installs. Then:

  1. pnpm run build:admin — it runs endora generate, which names the package's ./admin in the admin's contribution registry and its ./blocks.css in the admin's stylesheet, and then builds the admin.
  2. pnpm run module:install <module id> — the module's lifecycle install, which creates the Setting an operator switches it on and off with.
  3. Restart the backend. Its e-mail renderers are registered at boot.

There is no line to add to any file of the instance.

The block stylesheet​

./blocks.css is one finished stylesheet. Every selector is under a class prefixed with the module id, and colours and fonts come from the storefront's theme custom properties with literal fallbacks, so the block follows the channel's theme and still renders on the admin canvas:

.acceptance_blocks-badge {
display: inline-block;
padding: 0.25rem 0.625rem;
border-radius: var(--r-md, 6px);
background: var(--brand-600, #2563eb);
color: #ffffff;
font-family: var(--font-sans, system-ui, sans-serif);
font-size: 0.875rem;
font-weight: 600;
line-height: 1.4;
}

No @import, no @tailwind, no @source, no element selectors. The storefront imports it through blocks:generate and the admin through endora generate.

When the module is switched off​

A block whose module an operator switched off is absent on every surface, and nothing is written to the stored content:

SurfaceWhat happens
Storefrontthe block renders nothing to a customer; with ?cms_admin=1 it renders a note naming the block
E-mailthe block contributes nothing to the HTML or the text; the message is still sent, and content holding the block can still be saved
Admin editorsa stored block is a visible placeholder that keeps its props; the block is not offered in the palette

The editors find a stored block by its place in the document — an object with a type beside its props — so the nodes inside a rich-text value (a paragraph, an image, a mark) are never taken for blocks and never become placeholders.

Switching the module back on restores all three, with no document changed in between. The storefront decides from the modules the backend reports as not present, so a block whose owner the backend does not know — an overlay module's — still renders. The same holds for a package the storefront has installed and the backend does not compose, and when the backend cannot be reached nobody is reported absent.

When a renderer fails​

A renderer that throws costs the page that one block. On the storefront and in the editors it becomes the same placeholder a missing renderer gets, and the blocks around it are untouched; in an e-mail it contributes nothing, the message is still sent, and the failure is logged with the block and its module.

Check the package​

Run the check in the module package:

pnpm exec endora check --rule check:block-renderers
FindingMeaning
foreign-block-namea renderer keyed by a block another module owns
undeclared-blocka renderer for a block the manifest does not declare, or not for that surface's context
storefront-importthe storefront layer imports outside its allowed set
raw-htmldangerouslySetInnerHTML whose value is not sanitizeRichHtml(…)
email-layer-importthe e-mail layer imports React, a Node built-in or anything outside the e-mail renderer
unscoped-stylesheet./blocks.css has a selector outside the module's prefix, or pulls in another stylesheet
layer-without-subpatha layer's sources exist and the exports map does not publish them

Keep old content rendering​

A block's name is permanent, and its stored props outlive the version of the module that wrote them. A renderer must draw every shape of props the module ever published: ignore a prop it does not know, and fall back to a default for one that is missing. A change that cannot be made that way is a new block under a new name, with the old renderer kept.

Component name namespacing​

Block names are unique platform-wide, and the module-id prefix is what makes them so: cms.Text, catalog.ProductCard, promotions.PromoBanner. Two modules cannot declare the same name — the owner segment must be the declaring module's id — and if a collision reaches the registry anyway it throws DuplicateBlockNameError rather than letting one module's block replace another's.

Context availability (contexts)​

Every component declares which Page Builder surfaces may expose it via contexts:

ContextUsed by
cmsCMS pages, blocks, templates, blog
emailTransactional email editor
newsletterNewsletter campaigns (alias of email-safe set)
invoiceInvoice PDF template editor

Declare them on the block in the manifest. contexts is required and must name at least one surface:

contexts: ['cms'], // CMS-only

A block without email / invoice in contexts never appears in those editors (e.g. a product carousel). A module ships renderers for the cms and email contexts; newsletter shows the email blocks, and invoice blocks are drawn by the invoices module.

Responsive props and visibility (CMS only)​

The CMS Page Builder supports per-breakpoint overrides with inheritance (mobile ← tablet ← desktop). Use createResponsiveField from @endora-commerce/page-builder-core for individual props and withResponsiveVisibility for a per-component Visibility control.

Default breakpoints (configurable via Settings cms.page_builder.breakpoint.* or env CMS_PB_BREAKPOINT_*):

  • Mobile: < 768px
  • Tablet: 768–1023px
  • Desktop: ≥ 1024px

A responsive value is stored either plain (one value for every breakpoint) or as { base, tablet?, desktop? }, where base is the mobile value. The editor always writes base. A value written without it — through the API or an import, for example { "desktop": 2 } — means no value below the first breakpoint that has one: the breakpoints below render as if the option were unset, and that breakpoint and the ones above it take the value. normalizeResponsive and resolveResponsive from @endora-commerce/page-builder-core read it that way, so a renderer that goes through them needs nothing more; an object whose keys are not only base, tablet and desktop is a plain value, never a responsive one.

Email and invoice builders use a single layout width and do not expose responsive fields.

Email builders (transactional + newsletter) do not use CMS Mobile / Tablet / Desktop viewports. The authoring canvas is fixed at 600px (mail width). A Preview modal offers 600px / 320px HTML frames. Color fields reuse the CMS color palette.

Nesting (slots)​

Layout components (Row, Columns) use Puck slot fields — nested content is stored in props, not the legacy zones map. Since feature 163 the panels of cms.Tabs and cms.Accordion are slots too (items[].panel, which refuses cms.Column, cms.Tabs and cms.Accordion), and the Carousel's slides slot takes the four carousel item blocks besides cms.Slide. Do not declare a slot prop as translatable: the blocks inside it declare their own.

Box model (CMS layout + content)​

Layout and content components expose outer spacing (margin), inner spacing (padding), and border fields on the Responsive tab. Values support uniform or per-side editing. Columns use a responsive column count (1–12 per breakpoint) with equal-width tracks.

Use createSpacingField, createBorderField, and createColorField from @endora-commerce/page-builder-core when adding new CMS components.

Sections​

Section settings — anchor, colour scheme, background, spacing, width, content position and entrance reveal — live on one block, cms.Section, as its own top-level props beside a slot that holds any other blocks (the CMS module page describes what an editor sees): anchor, scheme, background, width, customMaxWidthPx, reveal, and per breakpoint spaceTop, spaceBottom and contentPosition. The three per-breakpoint props are the block's responsiveFields; their fields carry PB_RESPONSIVE_METADATA, so the editor shows them on its Responsive tab and they edit the breakpoint its scope switcher selects. @endora-commerce/page-builder-core exports the custom fields the plain Puck ones cannot express — createSectionBackgroundField, createSectionSpaceField (responsive), createSectionAnchorField, createSectionRevealField — and isSectionBackgroundField, by which the admin gives the background its asset picker. No other block carries section settings: a block outside a Section renders exactly as it does on its own, and a full-bleed look is a Section with the Bleed or Full width around the block.

An aspect ratio per breakpoint as a block's own prop (cms.Video.aspectRatio, cms.Image.ratio) is createAspectRatioField({ label, defaultRatio, allowAuto }) from the same package: a responsive field on the Responsive tab, offering every aspect token and a custom w:h. A ratio nested in a composite value (the hero's or the media-and-text video) uses ResponsiveRatioControl from @endora-commerce/page-builder-admin, the image field's in-field switch.

A Section stands only at the top level of a page:

  • every slot of every block refuses it — list cms.Section in a new slot's disallow (or leave it out of its allow), as the built-in slots do;
  • the editor guard shouldRevertPuckAction from @endora-commerce/page-builder-core/editor/puck-guards reverts an insert or a move of a root-only block (ROOT_ONLY_TYPES) into any zone but the page's own list;
  • a Section stored nested anyway renders its children with no section wrapper.

The one exception is cms.SectionGroup, a top-level container whose slot allows cms.Section only. It is root-only too (in ROOT_ONLY_TYPES, so list it beside cms.Section in a new slot's disallow); the guard lets a Section into a group's content zone and nothing else (isSectionGroupContentZone, SECTION_GROUP_CHILD_TYPES). It renders through SectionGroupFrame: a <div class="cmsc-section-group"> with the group's anchor, scheme and spacing (--cmsc-group-p(t|b)(-md|-lg)) and one .cmsc-section-group__paint layer — scheme background, paint, media and the decorative layer, spanning the window — behind all its Sections. A Section in it renders as a top-level Section (data-in-group), transparent (data-transparent) when the group paints and the Section has no background of its own and no other scheme.

The block renders through SectionFrame from @endora-commerce/cms-components, which at the top level (or directly in a top-level group) draws <section class="cmsc-section" id=… data-cmsb-scheme=… data-width=…> with the background layer, the padding and the content frame, and nested elsewhere renders the children only. An image background is a <picture> (object-fit cover, or contain) unless its size is auto, px or % or it has a repeat: then it is one .cmsc-section__tile in the media layer, painted as a CSS background from --cmsc-tile-image (--cmsc-tile-image-mobile below 768 px). The decorative layer's decorativeSize, decorativeRepeat and decorativePosition are written inline on the section or the group's paint.

A renderer that needs to know where it stands reads useSectionContext() from @endora-commerce/page-builder-core: {depth, topLevel}. The hero uses it to load its media eagerly only as the page's lead block — the first top-level block, the first block of a first top-level Section, or the first block of the first Section of a first top-level Section group. The depth comes from withHideOn, which every block carries; EmbeddedBlockDepth lets cms.InsertBlock render an embedded tree at its own depth, so a Section in an embed at the top level is a section and the same embed inside a column is not. A block that sends the visitor back to the page reads useSectionAnchor() for the anchor of the Section it stands in; newsletter.Signup does.

Brand variables (--cmsb-*)​

The brand settings reach the page as CSS custom properties prefixed --cmsb- — colours, the scheme colours, fonts, the type scale, button shape, spacing and widths. The full list is on the CMS module's Brand settings page. A block stylesheet that should follow the brand reads them, always with a literal fallback:

.acme_promotions-banner {
color: var(--cmsb-fg, #15202b);
background: var(--cmsb-bg, #ffffff);
border: 1px solid var(--cmsb-border, #d9e0e7);
font-family: var(--cmsb-font-body, Inter, system-ui, sans-serif);
padding-block: var(--cmsb-space-m, 24px);
}
.acme_promotions-banner__cta {
background: var(--cmsb-color-primary, #1261a6);
color: var(--cmsb-color-on-primary, #ffffff);
border-radius: var(--cmsb-btn-radius, 8px);
}
  • The fallback is what the block looks like with no brand settings — the cms module switched off, a failed read, or a surface that does not inject them, such as the e-mail editor. Use the value the block had before it read the variable, so introducing the variable changes nothing on an instance that never opens the Brand screen.
  • Read the scheme variables (--cmsb-fg, --cmsb-bg, --cmsb-fg-muted, --cmsb-border, --cmsb-link) rather than fixed colours for text and borders. A Section with a colour scheme rebinds them, so the block follows a dark Section with no code of its own.
  • A colour prop may hold a brand colour reference, token:<role>. resolveColorValue(value) from @endora-commerce/page-builder-core turns it into var(--cmsb-color-<role>, <built-in>) and leaves a hex value as it is.
  • The built-in blocks follow the same rule: packages/cms-components/src/brand/fallback-parity.test.tsx renders them with no brand settings and compares the result with the values they had before.

Server-read data: the block-data seam​

A block that shows data from another module — products, categories, blog posts — must have that data in the server-rendered HTML (Principle VII), so the read is lifted out of the block:

  1. The block declares its request as data. The kinds are a closed union in @endora-commerce/cms-components/utils/block-data (packages/cms-components/src/utils/block-data.ts): products-by-slugs, products-list and categories (owner catalog) and blog-posts (owner blog).
  2. The storefront resolves every request on the page before rendering — resolveBlockDataFor(documents, ctx, modules) in storefront/lib/page-builder/block-data.ts, mounted through storefront/components/BlockData.tsx — and skips a request whose owner module is absent (blockDataOwnerOf), so a module that is switched off costs the page nothing. A failed read is left out; the block renders its empty state and the rest of the page is unaffected.
  3. The block reads its answer with useBlockData(request) from @endora-commerce/cms-components/hooks/use-block-data (the key is blockDataKey(request)). In the admin editor, which has no server render, the same hook fetches through the preview readers that AdminCatalogPreviewProvider registers.

The seam was catalog-only before feature 163 and was generalised for blog.LatestPosts. Its old subpath, @endora-commerce/cms-components/utils/catalog-block-data, is kept as a deprecated re-export under the old names (collectCatalogBlockDataRequests, resolveCatalogBlockData, CatalogBlockDataSource and the rest), because a storefront created by an earlier release imports it. New code imports utils/block-data.

The union is closed: a module package cannot add a request kind of its own today. A module-owned server-data hook is on the follow-up list below.

Changing a block that is already in use: extend, don't narrow​

A built-in block may be reshaped, but an editor must never lose an option they had. Feature 163 reshaped the hero, heading, button, feature list, stats, testimonial, tabs, accordion, carousel and product listings under these rules, and a block author changing any block should apply them too:

  1. Keep a superset of the options. Every field the block had keeps the same or an equivalent control. Ask of every change: "what can an editor do before this change that they cannot do after it?" — the answer must be "nothing".
  2. Tokens are defaults, not a cage. Where a block starts reading a brand token (size, font, colour, spacing), keep a Custom literal override (px, hex, font family) in an "Advanced" group.
  3. Neutral defaults. New props default to today's look: no overlay without media, start alignment unless the block was centred, section headings at h2/h3 sizes, one primary button.
  4. Old content keeps rendering. Map the earlier props to the new shape in a pure function (the built-in blocks call it <block>FromLegacy), apply it when rendering and in the block's resolveData, and make it idempotent. A stored page then renders as before, and the editor converts it the next time it is opened (see Keep old content rendering above).
  5. Prove it. Add the block's case to the option-parity test, packages/cms-components/src/components/option-parity.test.ts, before the reshape: it records the fields the block had as literals and fails while any of them has no counterpart. Add the block's default render to the fallback-parity test.
  6. Remove a block only with a full equivalent. cms.ImageSlider was removed only once its parity case showed that Carousel image items carry every option it had. Stored content of a removed block degrades to the missing-block placeholder; the name is never reused.

Built-in Icons / Social​

  • Icons — curated Lucide allowlist (~100 icons) in packages/cms-components/src/components/icon-catalog.ts with a visual grid picker (IconPickerField). Do not expose the full Lucide catalog.
  • Social — brand icons via react-icons/fa6 (Facebook, X, Instagram, LinkedIn, YouTube, TikTok, …). Array items use getItemSummary so the selected network name appears in the Links list. Layouts: icons-only | icons-with-labels | vertical-list | pills.

Additional landing components​

The full block list, with what each block offers, is on the CMS module page. Two of them are often confused:

ComponentPurpose
newsletter.SignupSubscribes through the newsletter module: topics as tags, a required consent, works without JavaScript. Present only while newsletter is.
cms.NewsletterSignupPosts to any external form endpoint (actionUrl), for a newsletter service outside the platform.

Suggested follow-up (deeper integrations)​

PriorityIdeaWhy
Done (feature 163)Newsletter signup ↔ the newsletter modulenewsletter.Signup posts to the storefront's /newsletter/subscribe, which subscribes in the request's sales channel with source cms-block.
MediumA module-owned server-data hookLet a module's ./storefront layer declare an async resolver for its own blocks, instead of adding a kind to the closed block-data union in cms-components. It changes the server-rendering boundary of the Page Builder renderer, so it needs its own specification.
MediumIslands for static blocksThe whole Page Builder tree hydrates today. Rendering static blocks as server-only islands would cut the JavaScript a page sends and the work done on hydration.
Mediumhreflang with per-language URLsOne storefront URL serves every language, so pages announce their other languages as og:locale:alternate only. hreflang alternates need language-specific URLs first.
LowContact ↔ forms modulePick an existing form instead of iframe URL

Accordion / Tabs already cover FAQ-style sections; prefer those before a dedicated FAQ component.

Testing​

Use backend/acceptance/block-renderers-fixture/ as the template for a package that ships renderers, and endora check as its first test. backend/test/integration/cms/page-builder-extension.test.ts covers the declaration half: a manifest's blocks reaching the descriptor.