Skip to content

Hyvä CMS Architecture and Technical Overview

Hyvä CMS is a component-based content system for Magento. Content is stored as structured JSON, rendered through Magento templates, and edited through the Liveview Editor.

This architecture gives merchants a visual editing workflow while developers keep control over component fields, rendering, data access, validation, and theme integration.

Module Overview

Hyvä CMS is split into modules with clear responsibilities.

Module Responsibility
liveview-editor Core editor UI, preview system, component discovery, version history, translations, Tailwind JIT integration, preview security, editor preferences, and component CLI tools.
hyva-cms-magewire Internal Magewire fork used by the admin editor. It is customized for the Hyvä CMS admin panel and is not intended as a storefront dependency.
magento-cms Integration with Magento CMS pages and CMS blocks, including storage tables, rendering plugins, REST APIs, GraphQL queries, version history, and Tailwind CSS storage.
magento-attributes Integration with product and category EAV attributes such as descriptions. It resolves compatible attributes, stores attribute content, and replaces frontend attribute output when Hyvä CMS is enabled.
components-base Built-in component declarations and templates such as rows, columns, headings, images, banners, cards, accordions, CMS blocks, widgets, and product sliders.
scheduling Scheduled publication for supported Hyvä CMS content providers.
template Templates, snippets, preview thumbnails, default templates, and template/snippet editor providers.
cms-import-export Transfer Center ZIP import/export, JSON import/export, media handling, translations, history, and instance component transfer.
instance-components Admin-created database-backed components.

Supported Content Types

Core modules support:

  • CMS pages
  • CMS blocks
  • Product attributes
  • Category attributes
  • Templates
  • Snippets

Hyvä Commerce companion packages can add further content types through the same provider contracts, storage model, and Liveview Editor — for example, Menu Builder adds navigation menus.

Custom modules can add more content types by implementing the Hyvä CMS provider contracts and editor integration. See Extending for Other Content Types.

Component Discovery

Code-defined components are declared in etc/hyva_cms/components.json files inside Magento modules. The component collector scans installed modules, validates declarations against the JSON schema, processes includes and option sources, and builds a unified registry.

The registry contains the component label, category, template path, fields, child-component rules, descriptions, context flags, and variant settings. In production mode, component data is cached in the hyva_cms cache. Developer mode keeps iteration faster by avoiding stale component cache behavior.

Database-backed instance components are collected separately and merged into the same provider registry with the instance/ prefix.

Content Storage

Hyvä CMS stores content as JSON component trees. A content item usually has separate draft and published content, plus version history and Tailwind CSS data.

CMS pages and blocks use dedicated Hyvä CMS tables that reference Magento's native cms_page and cms_block records. Product and category attribute content uses dedicated attribute liveview tables and stores enabled attributes plus base and store-specific content.

Version history is stored separately so merchants can restore or compare earlier versions without changing the current draft or published state.

Rendering

When Hyvä CMS is enabled for a supported item, frontend rendering loads the published Hyvä CMS JSON and renders each component using Magento's template system.

The root renderer walks the component tree and delegates each component to its declared PHTML template. Component templates receive Hyva\CmsLiveviewEditor\Block\Element, so they can use helper methods for editor attributes, images, links, child rendering, classes, block IDs, and rich text output.

In preview mode, Hyvä CMS injects the editor integration attributes (such as data-liveview-element and the root getEditorAttrs() values) into each component's first element automatically, and strips them from public storefront output. Templates can opt out with $block->setData('auto_attributes', false).

For product and category attributes, frontend plugins replace the native attribute HTML with rendered Hyvä CMS content when content is enabled and published.

Liveview Editor

The editor uses the internal hyva-cms-magewire module for reactive admin state. The main editor component keeps the content tree in memory, handles field changes, saves drafts, publishes content, and coordinates preview refreshes.

The preview iframe loads a storefront URL. Editor updates are pushed into the preview so merchants can see the result without full page reloads. Preview URLs use security tokens that allow draft preview sharing without publishing the content. The editor and preview communicate through a structured postMessage layer, the Liveview Bridge.

Editor features include:

  • Navigator and a tabs bar for recent content
  • Responsive preview modes and split view
  • Context editing directly in the preview
  • Rich text editing with TipTap, including Magento variables and directives
  • Monaco-powered HTML editing
  • Version history, plus session-level undo and redo
  • Translations
  • Templates and snippets
  • Transfer Center
  • Scheduling
  • Per-user editor preferences, favourite components, and keyboard shortcuts
  • Instance components

Tailwind CSS

Hyvä CMS generates Tailwind CSS for content so that classes used in components produce styles without a full theme rebuild. Generated CSS is scoped to each entity with a wrapper selector in the form .hcms-{type}-{id} (for example .hcms-page-42), which keeps content styles from leaking into the rest of the page. CSS is stored per entity, theme, and edition (draft, published, or scheduled).

Compilation can run in one of two ways, selected in store configuration:

  • In-browser Just-In-Time compilation, which compiles styles in the editor. This is the default.
  • Server-side compilation through a Node-based Tailwind compiler.

Both paths produce the same scoped output and support Tailwind v3 and v4. The strategy toggle is provided by the hyva-themes/commerce-module-cms-tailwind-jit-bridge package. For configuration, the server-side recommendation for new projects, and backward-compatibility details, see Tailwind CSS Compilation.

Projects should still prefer component templates and design-system options over asking merchants to enter Tailwind classes manually.

Scheduling

The scheduling module stores releases and scheduled items separately from drafts and published content. Cron publishes due releases by asking the registered schedule provider for each content type to apply content, Tailwind CSS, version history, and any content-type-specific settings.

Hyvä CMS scheduling is separate from Adobe Commerce Content Staging.

Templates, Snippets, And Instance Components

Templates and snippets are stored as Hyvä CMS content providers. Templates act as full starting layouts. Snippets store selected components that can be inserted into other content.

Instance components are database-backed component definitions. They can define fields and a lightweight HTML template through the admin UI. They are merged into the normal component registry and can be exported with content that uses them.

APIs

REST APIs expose admin CRUD operations for CMS pages, blocks, version history, Tailwind CSS records, catalog attribute content, scheduling entities, templates, and snippets. GraphQL exposes published CMS page and CMS block content for frontend use.

See Hyvä CMS APIs.

Developer Extension Points

Developers can extend Hyvä CMS by:

  • Creating code-defined components.
  • Overriding base component templates or declarations.
  • Adding custom field types.
  • Registering option sources for component fields.
  • Adding support for custom content types.
  • Adding schedule providers for custom content types.
  • Adding custom instance-template field renderers.
  • Integrating with REST APIs or GraphQL.