Headless CMSs are awesome because they give you 100% control over your front end. However, things quickly get messy when you have one part of your data structure in the CMS and another in your app's database.

Let's say you're building a travel app where users leave reviews for cities. In addition to user-generated content (like the reviews), you have a content team that adds curated photos and writes about the cities.

You design the content data inside your Headless CMS so your team can benefit from its easy-to-use editorial interface. For the reviews, you create the structure using SQL and your database. Then, in your app's city screen, you merge the two sources using a slug identifier in both databases.

Initially, this development process seems harmless. After all, the alternative is to build a custom admin interface for your non-technical team to write HTML and upload images, which could take weeks or even months.

But over time, the added complexity of having two sources of truth has a compounding effect.

Data design becomes tricky

Every time you need to add a data structure you must decide if it should live in the CMS or the database. Then, you should define how you'll merge data to display it.

Different query languages to filter data

In addition to SQL, you and your team must learn a proprietary query language to filter data in your CMS. Sometimes you can use GraphQL to fetch data from your CMS, but it's still a separate language from SQL.

Inconsistent data leads to time-consuming bug-hunting

Because you cannot enforce referential integrity by using foreign keys between CMS data and your database, weird bugs appear out of nowhere. In our example, what happens if the content team changes the slug for New York City from ny to nyc? Without updating it on the database, you'd probably see no reviews for it in your app.

Performance and UX suffer

Without the ability to join data before sending it over the wire, you should be very careful when merging CMS data with SQL data to avoid making your app slow. Inexperienced developers commonly make one SQL query for each record in the CMS, or vice-versa. But even when you do only one query for each data source, you still have to merge it with code, which is way slower than joining at the SQL level.

Training new team members is harder

Every new hire must learn how to work with the CMS and the database, as well as the patterns you use to merge data. And because of all the other reasons above, they are prone to making mistakes until they master your workflow.

Searching for a single source of truth

In my journey building dozens of apps, as I tried to avoid the pitfalls above, I constantly strived to have a single source of truth for my data. Every time I spread data across different sources, I made my process exponentially more complex.

But because I knew how hard it is to build a great UX for non-technical people to manage content, I insisted on trying to use Headless CMSs. Out of a dozen projects I used them on, only one was successful in the long run. And guess what: it was the only one that had 100% of the data on the CMS side, with no relational database.

With that lesson learned, I then tried to have all my data on the CMS, even for complex apps. But, even though they offer custom data types and querying APIs, CMSs are not databases. They're too limited for application development, while relational databases thrive in this scenario.

As the next stage in my quest, I decided I didn't want to have two sources of truth and needed a relational database. So I made a hard trade-off: I would build custom CMSs and admin panels for my apps, always using only one database. That led me to a more sustainable path, but it required a ton of custom development, which was expensive.

Finally, my partners and I built Flashboard to create instant CMSs for our existing databases. We now have the best of both worlds: a great CMS experience for non-technical team members without reinventing the wheel at each new project.

Flashboard is free for solo teams, so give it a try if you're considering a Headless CMS. But even if you decide not to use it, keep the trade-offs I described in mind as you choose between building a custom CMS or using an existing one.