Skip to main content

Leader’s Guide To Overcoming Challenges with Headless CMS

Leader’s Guide To Overcoming Challenges with Headless CMS
Headless CMS and composable architecture solutions are great decoupling code and content, but they come with their own challenges. A form-based interface doesn’t reflect the live, user experience, and exposes non-technical employees to the site’s complex content architecture. This often makes your site a liability to maintain, rather than a revenue generating asset.


As marketing teams create more content to engage with customers and drive business impact, they face many challenges. Chief among these are the difficulty of managing content across multiple channels and the inability to work independently from dependency on developers.

Headless CMS and composable architecture solutions are designed to provide a centralized content hub that can be used to create and manage content across a variety of channels. With content decoupled from the code, it can be changed quickly and independently. But headless  solutions come with their own challenges. A form-based interface doesn’t reflect the live, user experience, and exposes non-technical employees to the site’s complex content architecture. This often makes your site a liability to maintain, taxing both engineering and marketing teams — rather than a revenue generating asset.

We’ll cover some of these challenges and advice on how to avoid them.

Headless CMS are Extremely Useful

We’re assuming that if you’re here, you already know what a headless CMS is, if not, here’s a good resource to learn more about it.

As you probably know, headless CMS are very useful. Their primary benefit is allowing code changes to be made independently of content changes, and vice versa.

This means that developers can work on code and components, while marketers can write and edit content in a no-code UI without being dependent on developers.

The main challenges of a headless CMS

Headless CMS platforms like Contentful, Sanity, or Contentstack are amazing tools for developers. Companies run into trouble when they expect their headless CMS to be a good editing environment for non-technical business people, like marketers. Below are the challenges you can expect to encounter, or are perhaps already experiencing (and yes, at the end of this piece we’ll also make some suggestions how to overcome them, so skip ahead if you must).

All these problems cripple team efficiency. Marketers are blocked by developers and cannot change the site, while engineers spend time and effort supporting content changes instead of innovating and creating new, engaging digital experiences. Your teams lack independence, increasing the time to market of each change, reducing job satisfaction and, ultimately, wasting revenue opportunity.

“It’s not only about combining all the pieces of the composable stack that will give you the solutions. At the end of the day. We believe that you have the control of designing your own editing experience and the tools that you need.” — Dan Barak, CEO & Co-Founder, Stackbit

1. A form-based UI

This requires very little explanation. When building a website, one has to deal with a lot of visual aspects like placement, color, and even how text is positioned. Selecting a color from a dropdown on a form is a counter-intuitive experience that tells the marketer almost nothing about how the live page will look. The same goes for image size, text wrapping on a smaller or mobile screen, etc. We’ve become very much accustomed to drag-and-drop UIs that are fully visual and reflect the end result. Going back to a form-based UI feels like a huge step back.

2. No preview

Okay, so you’ve compromised and have to work with a form-based UI. Oftentimes, this means seeing your work requires you to publish the page, i.e. ship it to production. This is problematic on so many levels, from risking breaking a page in production, to simply shipping something that doesn’t look good. This problem is exacerbated by modern static sites that take longer to build, as the time an error might be in production can span several precious minutes until the whole site rebuilds, even if you correct it immediately.

Developers can spend time building and properly connecting a preview environment. That’s a good and necessary step you should insist on. It’s still not enough, though. Just like the actual site, it often takes time to spin up, and it’s never interactive — you still have to edit in a form-based UI, press a button, wait, and only then see the preview, costing you time at every step along the way.

3. Working without context

None of the components of a webpage live in isolation. Sections live below, above, to the side and sometimes even overlap. The particular combination of components is what makes a page a complete digital experience.

Unfortunately, the headless CMS is purely focused on content, and its visibility is almost always constricted to a single component. You can navigate up and down in the information tree, but the main focus is always on the current component. This makes it extremely hard to imagine the interplay between separate components, and to see how they work together to form a page.

Context is everything. Being able to easily understand how the piece you’re currently working on connects with others and where it resides on the overall page is paramount.

By definition, a headless CMS deals only with the content and doesn't care about the “head,” or where the data is actually presented. So it doesn't solve the issue of context.

4. Requires understanding complex underlying data models

Often, to be able to work in a headless environment, one needs to clearly understand how the components and content have been modeled (aka the content schema).

Take the top, or “hero” section of a website. It’ll usually contain some text on the left, with an action item on the bottom, and a piece of media on the right.

If the engineering team decided to build a fairly robust and flexible system like Atomic design, creating that hero section would require multiple steps. You wouldn’t simply implement a single component, but would have to add a row with two columns. The first column would require four rows (each containing a large label, a smaller label, a text area, and a button, respectively), with the second one containing the media. For what should be a simple section, it’s quite a structure to learn, understand, and apply each time you need it.

You could also instruct your engineers to create components that serve a specific purpose and don’t expose the inner structure, making an action like adding a hero section easier. However, that decision will cost you flexibility. If you decide you’d like a form instead of that image, or a checkbox with text beneath that button, your engineers will have to reconstruct a whole new component, or add more controls to the existing one. This wastes engineering time and creates either too many similar components, or adds too many levers and controls to your existing components.

5. Embedded vs. reference objects

The ability to reuse content across multiple areas of your website is a great benefit of headless CMS. But this blessing can easily turn into a curse.

A reference object is one that can be included in multiple pages and locations, by simply pointing (or referencing) the same object from all those places.

But an embedded object is fully contained within the context that surrounds it, like a single web page or section.

Changing a reference object results in the same change being reflected throughout all the locations pointing to that object, while changing an embedded object generates a localized change only.

Both these types are very useful — the former could be a footer across your entire site, or a specific unit that’s repeated in multiple pages and must always be the same. Meanwhile, the latter could probably be prevalent on every single page on your website.

The real problem, which ties to the lack of context mentioned above, is knowing which section is which and understanding if the change you’re making will be localized or affect the entire site. This problem becomes even more complex as some CMS only have reference objects, so it’s now a matter of trying to understand if anyone uses this particular object anywhere else.

6. Can’t switch abstraction layers

This relates to a few of the points mentioned above, but it deserves its own explanation.

The developers building your website have a chance to choose the level of abstraction at which your components and content will be represented. On one extreme, you have Atomic design, where there are basic atoms (like a button, a label, and so forth) that combine into larger molecules, even larger organisms, etc. On the other side, you could have a very prescriptive design system, built only from individual page types (landing page, home page, contact page), each with its fixed layout that cannot be altered.

Once an organization makes a choice in a traditional CMS, they’re stuck with it. Many will prefer to have as much flexibility as possible, but that means that every time a larger section on a page is built, a plethora of objects need to be created and composed together.

The sweet spot as a marketer is to have easy access to the many components you use on a regular basis, with the flexibility to alter an existing component or assemble one from scratch without having to run back to the developers.

7. Complex publishing workflows

The headless CMS contains all the content your organization uses across its assets. When you’re trying to ship a new landing page, you’re creating a bunch of new objects, embedding them in each other, changing their fields, etc. But when it comes time to publish, selecting a specific component to publish isn’t always evident or easy.

Moreover, organizations often have approval flows before letting a piece of content go live. Imagine working with the wrong abstraction layer, using a form-based UI and a clunky preview that takes too long to build each time. All that to submit for approval from a person that just needs to see your changes and how they look in the real world. The more complex the process, the harder it will be for them to understand what they’re looking at.

“It’s not just about web … I need my experiences to be able to work in product, across apps.” — Jason McClelland, CMO & Customer Care Officer, Shutterstock

8. Multiple data sources

With all the challenges we’ve enumerated so far, at least you can go to one location and change all the content that appears on your site…right? Well, often that’s actually wrong, because most sites have multiple data sources. This could be a second headless CMS from a small company you acquired a couple of months ago; some user info stored in your internal legacy database; an Airtable sheet your local teams in the field use; even your product catalog.

Now, whenever there’s a change to be made, you have to remember — or guess — where that data is coming from, log into that system, and make the change there.

Let’s assume that you’ve successfully made all these changes separately, but you now need to have them all update to production at the same time, at 5 a.m., on Black Friday…good luck.

“The bigger you are as a company, the more content sources and complexities you have, the less chance of a perfect fit.” — Dan Barak, CEO & Co-Founder, Stackbit

What solutions are out there?

Don’t be disheartened. There are many challenges, but also many benefits to headless CMS solutions, and new tool categories are sprouting to help tackle these problems.

Some choose to go for tools that call themselves a “visual CMS,” but those end up acting more like a traditional site builder. Code has to be written in a very specific way to work with this semi-closed ecosystem, costing you the benefits of headless and truly composable architecture.

To get the best of both worlds, you should keep your headless CMS of choice that your developers have chosen and layer a visual editor like Stackbit on top. Stackbit partners with and supports all headless CMS, integrates in minutes, and doesn’t require your developers to do anything differently. Crucially, it also doesn’t introduce extra dependencies or vendor lock-in.

Stackbit reflects all your content from the headless CMS in a visual editor on top of a live preview, allowing non-technical employees to work in context, save customized components and set workflows. You can update content on the spot without worrying about how it was configured to be stored by engineering, and simply ship it to production in seconds.

Schedule a call to see a demo today.

Company logo


Drive more revenue from your website with a visual editing interface that works with your tech stack in minutes.