Disclosure: I am the creator of Headcode CMS (www.headcodecms.com), and I created the software out of a specific need and vision, which I will outline in this article.
Why did I create Headcode CMS?
I’m a freelance web developer and Shopify consultant. For web development, I prefer to use Next.js in combination with Supabase. But I also support clients creating Shopify online stores and custom Shopify apps. Even if I love headless e-commerce using Shopify Hydrogen — and I’m convinced this will be the future — I almost always recommend my clients to start a new online store project with Shopify’s traditional Online Store 2.0 system. From there, I customize the theme to their specific needs using Liquid templating.
- My clients can select a brilliant theme from the official Shopify theme store. The theme developers usually spent months in the making, added cool animations, and paid attention to every detail.
- After choosing a theme, my clients can immediately start adding text and images. Shopify’s theme editor is excellent and easy to use.
- Using the Liquid templating language, I can easily add new sections or customize existing ones.
As mentioned above, I prefer to create websites using Next.js. But when my clients want to edit content themself — and don’t want to use Markdown via GitHub — I must choose a headless CMS. I like Payload CMS and Sanity, but with either solution, it is significantly more effort to get to the point where my client can add their text and images. I already had a project where we decided to set up a Shopify store, even if we did not plan to sell products, just because we found a beautiful Shopify theme and could start immediately.
I wanted to change this. This is why I created Headcode CMS.
Some of my main goals are:
- It must be free to get started, with as few dependencies as possible.
- The main focus is on developer experience and reusability.
- Utilize existing solutions, e.g., Supabase for cloud database, storage, Auth, Vercel Visual Editing and Deployment Previews, GitHub and Git Branches for versioning, Next.js for performance, image optimization, etc.
I started implementing the first prototype in January 2023 and was very excited about the results. Since then, I continued to iterate on it as a side project, and in September 2023, I was ready to present a working version as a developer preview to the public. You can install it from this GitHub repository: headcodecms/proto01.
In addition, I created a video outlining all major features of Headcode CMS.
Vercel Visual Editing
Headcode CMS has an administration app with all the features you need to manage the website, from setting up the database to a media library for your images and managing users.
But content editors like to have context. They usually browse the existing website and want to add text or images directly at the current location. In May 2023, Vercel introduced Vercel Visual Editing to their platform, which enables contextual (on-page) editing for content management systems.
Furthermore, Vercel’s Visual Editing feature aligns perfectly with my idea of versioning, content preparation, and deployment.
Versioning — Integration with GitHub and Vercel Preview Deployments
Versioning is my favorite feature of Headcode CMS. I’ve worked on many CMS projects in the past. Almost always, the content teams had the following requirements:
- Regular publishing cycles: Updates once or twice a week (e.g., every Wednesday)
- Public URL to share for review (e.g., for approval by managers)
- Test the entire website separately before publishing (e.g., desktop and mobile versions)
- Ad-hoc editing of the live website (e.g., fixing typos)
- Developers want to create new features individually (e.g., in branches)
Most Web CMS solutions integrate the versioning and publishing workflow into their main product and database. But this gets too complex, confusing, and hard to maintain.
With Headcode CMS, I implemented an extremely simple, flexible solution that integrates with the tools you already use: Git Branches, GitHub, and Vercel Preview Deployments.
You create a new version — optionally in a new Git branch — which clones the data of the current live website. Now, you have a wholly cloned environment where the editors can prepare their content, and the developers can implement new sections.
If you worked on a separate branch, you can deploy the branch to Vercel and have a live preview of the upcoming website with a public shareable URL.
Once you are happy with the preparation, merge the branch to your main branch, and you are live. You can always revert to a previous version if a serious error occurs.
Domain Objects vs. Generic Structure
Most headless CMS systems recommend you start with modeling your domain objects. For instance, this might be an employee object for a company website with a name, avatar image, job title, department, email, etc. Usually, this object is organized in a collection and used on the team’s page and as an author on a blog post. This has advantages but here are some disadvantages:
- The structure is more fragmented — the content editor must find the correct object to modify text.
- Manage relationships between objects
- Difficult to reuse content sections across projects
With Headcode CMS, I support a generic structure over modeling domain objects. Let’s take this simple section of cards I use to display the team.
This card has an image, title, subtitle, description, etc., and can be used to display the team but also products.
When I use an employee domain object and implement a specific team component, it may look the same, but it can only be used with the employee domain object. This makes reusing components across projects very difficult.
In the end, you decide which alternative is best for your project. I’m convinced that the generic structure of Shopify’s theme system is one important reason why Shopify became so successful.
Headcode CMS was fun to create, and I will continue improving it. Many innovations will be launched in the following months, like Next.js 14, view transitions, new build tools, Tailwind Catalyst, etc. My vision is to create a simple yet flexible alternative in the web CMS landscape that is built for developers, content editors, and reusability.
You can help me speed up development and sponsor Headcode CMS on GitHub.