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:
- 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. - 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
nameis<module id>.<PascalCaseName>, and the part before the dot must be the declaring module's ownid. The name is written into the stored page content and never rewritten, so choose it once. - A block's
categorymust be declared in the same manifest'sblockCategoriesfor 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' },
],
}
pathis 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.formatisplain(the default),tiptapfor a prop holding a TipTap JSON document, orhtmlfor 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 ownresolveDataregenerates 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 notranslatableat 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.
| Subpath | What it exports | Who renders with it |
|---|---|---|
./storefront | contributions — React renderers for the module's cms blocks | the storefront, in the server-rendered HTML |
./email | emailBlocks — pure functions that render the module's email blocks to HTML and text | the backend when it sends, and the admin's e-mail editor |
./admin | contributions.blocks — editor renderers, beside the module's routes and zones | the admin's CMS and e-mail editors |
./blocks.css | one finished stylesheet | the 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.typemust bemodule, andendora.idthe module id that prefixes its block names. A package without that block is not a module package:blocks:generatesays so in a note and registers nothing from it, and its blocks render as placeholders.fileslists everything anexportsentry points at —blocks.cssandtailwind.cssbesidedist. 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
typescondition above). A storefront written in TypeScript imports./storefrontfrom its generated registry, andblocks:generaterefuses a storefront layer that ships none asuntyped-layer. - A package with
./adminalso publishes./tailwind.css, which tells the admin's Tailwind build where the layer is.endora generaterefuses 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/coreandreact, with@endora-commerce/platformfor the backend. - The build is plain
tsc, which keeps a leading'use client'and emits the declarations. Relative imports are written with the.jsextension.
@source "./dist/admin";
Where the names in the examples come from:
| Name | Import 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
asynccomponent — 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(), noMath.random(), no locale-dependent formatting without the language fromuseBlockRenderEnvironment(); - every file of the layer starts with
'use client'.check:block-renderersdoes 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/contractsand 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:
| Refusal | Meaning |
|---|---|
untyped-layer | the package publishes ./storefront with no type declarations |
missing-layer-file | an exports entry points at a file the package does not hold |
layer-without-subpath | the package ships src/storefront/index.ts and declares no ./storefront |
duplicate-module | two 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:
pnpm run build:admin— it runsendora generate, which names the package's./adminin the admin's contribution registry and its./blocks.cssin the admin's stylesheet, and then builds the admin.pnpm run module:install <module id>— the module's lifecycle install, which creates the Setting an operator switches it on and off with.- 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:
| Surface | What happens |
|---|---|
| Storefront | the block renders nothing to a customer; with ?cms_admin=1 it renders a note naming the block |
| the block contributes nothing to the HTML or the text; the message is still sent, and content holding the block can still be saved | |
| Admin editors | a 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
| Finding | Meaning |
|---|---|
foreign-block-name | a renderer keyed by a block another module owns |
undeclared-block | a renderer for a block the manifest does not declare, or not for that surface's context |
storefront-import | the storefront layer imports outside its allowed set |
raw-html | dangerouslySetInnerHTML whose value is not sanitizeRichHtml(…) |
email-layer-import | the 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-subpath | a 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:
| Context | Used by |
|---|---|
cms | CMS pages, blocks, templates, blog |
email | Transactional email editor |
newsletter | Newsletter campaigns (alias of email-safe set) |
invoice | Invoice 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.Sectionin a new slot'sdisallow(or leave it out of itsallow), as the built-in slots do; - the editor guard
shouldRevertPuckActionfrom@endora-commerce/page-builder-core/editor/puck-guardsreverts 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
cmsmodule 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-coreturns it intovar(--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.tsxrenders 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:
- 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-listandcategories(ownercatalog) andblog-posts(ownerblog). - The storefront resolves every request on the page before rendering —
resolveBlockDataFor(documents, ctx, modules)instorefront/lib/page-builder/block-data.ts, mounted throughstorefront/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. - The block reads its answer with
useBlockData(request)from@endora-commerce/cms-components/hooks/use-block-data(the key isblockDataKey(request)). In the admin editor, which has no server render, the same hook fetches through the preview readers thatAdminCatalogPreviewProviderregisters.
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:
- 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".
- 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.
- Neutral defaults. New props default to today's look: no overlay
without media, start alignment unless the block was centred, section
headings at
h2/h3sizes, one primary button. - 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'sresolveData, 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). - 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. - Remove a block only with a full equivalent.
cms.ImageSliderwas 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) inpackages/cms-components/src/components/icon-catalog.tswith a visual grid picker (IconPickerField). Do not expose the full Lucide catalog.Social— brand icons viareact-icons/fa6(Facebook, X, Instagram, LinkedIn, YouTube, TikTok, …). Array items usegetItemSummaryso 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:
| Component | Purpose |
|---|---|
newsletter.Signup | Subscribes through the newsletter module: topics as tags, a required consent, works without JavaScript. Present only while newsletter is. |
cms.NewsletterSignup | Posts to any external form endpoint (actionUrl), for a newsletter service outside the platform. |
Suggested follow-up (deeper integrations)
| Priority | Idea | Why |
|---|---|---|
| Done (feature 163) | Newsletter signup ↔ the newsletter module | newsletter.Signup posts to the storefront's /newsletter/subscribe, which subscribes in the request's sales channel with source cms-block. |
| Medium | A module-owned server-data hook | Let 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. |
| Medium | Islands for static blocks | The 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. |
| Medium | hreflang with per-language URLs | One storefront URL serves every language, so pages announce their other languages as og:locale:alternate only. hreflang alternates need language-specific URLs first. |
| Low | Contact ↔ forms module | Pick 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.