Component systems and headless CMS platforms form a natural pair in the Jamstack: one provides reusable sources of truth for UI, the other exposes editorial content as data to any API-consuming client. Connecting the two is usually trivial. The hard part is keeping a consistent, reusable system of components in step with a CMS experience built for content editors. Free content entry and predictable component output are the two things headless content management promises — and often the two that collide.

The Button Problem

A single button component shows the tension. In React:

<Button to="/">Go Home</Button>

Inside a React codebase, <Button> takes two props: to and children, the latter being the React mechanism holding whatever sits between the opening and closing tags — here, "Go Home". Neither name means anything to the person publishing a button in a CMS. These are the common workarounds, and why each falls short.

Fields that mirror component props

Exposing to and children straight to editors does not work, helper text included, for beginners and experienced editors alike. Editors respond better to words like label or text for children and url for to:

Showing a mockup of CMS text input fields for a button component, one for a to field with https as a placeholder, and another for children with Buy Now as a placeholder.
😕
Showing a mockup of CMS text input  fields for a button component, one for a URL field with https as a placeholder, and another for Button Label with Buy Now as a placeholder.
🤓

The catch is that the CMS is now out of sync with the code.

Masked field attributes

Most headless CMS products let a field's displayed label differ from the name used in the delivered API payload. Labeling fields Label and URL while delivering them as children and to looks like clean separation of concerns — editors see familiar terms, developers keep their names. In practice it confuses developers: debugging an editor's issue means digging through an extra layer to establish the label-to-field-name mapping, which costs time.

Renaming the props

The other option is developer flexibility — simply switch the props. Using label and url works fine for CMS-originated data, but every in-code use of the button then looks like:

<Button label="Go Home" url="/" />

This shrinks what the button can do. Support for, say, an icon rendered inside the label now needs extra logic or another prop, whereas React's children would have handled it with little more than custom styling. Lean on flexibility alone and you end up fighting the framework or shipping props that feel wrong.

Transformers: Optimizing Both Sides Separately

The approach that works is to optimize the editor experience and the developer experience independently: craft a CMS experience tailored to editors, and a codebase that developers can navigate, understand and extend. Parity between the two is deliberately abandoned. Utilities then convert data from the CMS shape into the shape the front end expects, whatever the framework or tooling. Call them transformers.

Illustration showing a rounded square that says Data Source pointing to a yellow box that says transformer, pointing to another rounded square that says component. There is a small code snippet on both sides of the yellow square showing how it transforms the Label and URL fields to Children and To, respectively.

Where transformations should live is less settled. Three placements have been used, each with trade-offs.

1. Alongside the components

Keep transformers in the same folder as the components they serve, following the habit of keeping related files close together.

The same illustrated diagram, but the yellow box is now the button index.js file that points to a transformer.js file that then points to a button component.js file.

Each component gets a directory with a predictable set of files, and index.js acts as the controller — importing and exporting the others, which makes it simple to wrap rendering in logic-based behavior, transforming props before the component renders:

import React from "react"

import Component from "./component"
import transform from "./transformer"

const Button = props => <Component {...transform(props)} />

export default Button

The transform.js file might look like this:

export default input =&gt; {
  return {
    ...input,
    children: input.children || input.label,
    to: input.to || input.url
  }
}

Props passed as to and children pass through untouched; label and url are converted to children and to. The <Button> component in component.js only ever deals with children and to.

const Button = ({ children, to }) => <a href={to}>{children}</a>

The upside is logic tightly coupled to its component. The main downside is volume: many files and many transforms, even though a page's whole dataset could be transformed higher up the stack.

2. At the top of the funnel

Data enters the app through some retrieval mechanism, and developers use that mechanism to fetch as much of a page's or view's data as possible, since fewer queries and requests usually mean better performance. That mechanism therefore sits near the top of the funnel rather than having each component pull its own data dynamically (where that is necessary, adapters can handle it).

Another illustration, this time where the yellow box is labeled import mechanism, and it has three arrows, each pointing to a white square, labeled, component 1, component 2, and component 3, respectively.

That same mechanism could transform all of a page's data before any of its components render. Theoretically this beats the first approach: less browser-side work should improve front-end performance, and shifting work to the server is often preferable.

Practically, it is a lot of work. Data structures can be large, complex and interwoven, and passing transformed data down to components is laborious. Testing is harder too, because a giant blob fetched at the top of the stack has so much complexity and variation. With the first approach, a button transformer is trivial to test; here, you must account for button data wherever it might appear in the retrieved object. Still, done well, this is generally the better approach.

3. A middleman engine

The third option moves the work elsewhere entirely: build a small application that performs the transformations and exposes the content for the front end to consume.

Another illustration, this time where the yellow box is the abstracted data source, which points to a white box labeled import mechanism, which then points to the same three white squares representing components that are outlined in the previous illustration.

This is likely more work than the second approach, plus added cost and maintenance for an extra application that must be kept rock solid. Its major upside is abstraction: route incoming data for every front-end application through the engine, and a second project using the same CMS or data source benefits from work already done.

Rolling It Out

For teams not doing any of this yet, treat the three approaches as stepping stones whose complexity, maintenance burden and power grow with the application. Start with transformers alongside components. Move to top-of-funnel transformations when the benefits justify the work, and consider the middleman engine if you are feeling brave. What matters most is an experience that both editors and developers understand and enjoy.