Exploring Payload CMS: A Developer’s Perspective

CMSs are a sensible technology that allows development and production teams to contribute to a site to the best of their ability. Payload CMS is a newer option with version 1.0 having been released in 2022, and brings several desirable features for fluid development workflows. As a dev who has previously architected a Contentful-backed solution, I thought it would be interesting to compare that previous experience with how I might create a similar, reliable dev workflow in Payload.

Who Am I?

I'm a developer with over 20 years in the business who has been doing Web frontends for the majority of my career. I researched database systems in grad school, which gave me a deeper-than-average understanding of databases and relational querying. That's relevant here because CMSs are, at their core, just databases with fancy frontends. You figure out how your data is structured, then the data itself, and finally, the CMS engine gives you some help on the way to making a functional site out of said data.

The root problem of developing against a CMS

I'm now accustomed to a particular type of CMS: the Headless CMS, which has users define structure in the UI. "Headless" here means that the end product of the CMS itself is not the full application. This headless structure is a departure from traditional CMSs like SharePoint and Drupal, which also render their content into websites. In a headless CMS, developers write an application separately and fill it in with structured data served by the CMS. This is great except for one prominent annoyance.

When adding to the application, developers needing new object types or fields must add them in a web UI, separately from the code. The separation can be a maintenance nightmare because desynchronization between the deployed code and the CMS backing it will render a site unusable.

Personally, I always solve this desynchronization problem with migrations, but getting people not named Brad Momberger to stick to using migrations has been a much more difficult task than setting them up in the first place.

Payload CMS developers must also deeply feel this problem, as one of their key differentiators is their code-first, version-controlled approach.

In Payload, there are no "click ops" - as in clicking around in an Admin Panel to define your schema. In Payload, everything is done the right way—code-first and version controlled like a proper backend.

Payload also gets at the primary cause of much of the frustration around click ops—lack of version control. It can be difficult, if not impossible, to track down when and why a change was made and what other changes depend on it.

In this article, we’ll take a look at some of the other defining characteristics of Payload CMS and how it compares to other CMS options like Contentful.

Comparing Payload to Contentful

To compare Payload CMS to my previous experiences working on CMS-backed sites, I wanted to test it with a real-world scenario. I built an app for one of my hobbies—playing riichi mahjong. The app tracks “yakuman,” which are rare winning hands comparable to a royal flush in poker. This allowed me to evaluate Payload’s usability compared to Contentful.

Getting Started

Before diving into development, setting up a CMS is the first step. How smooth that process is can make or break an experience.

• Contentful: I first set up my account, space, and environment on the hosted CMS. Then, I manually created a Page content type with Title, Slug, and Content fields. Once the content type was defined, I stored an export of the content model as a backup and added a default Page object. After that, I generated API keys and set up my local development environment to interact with Contentful’s API.

• Payload: Setting up in Payload was much simpler. With npx create-payload-app, I initialized the project and had a functional template ready to go. The admin panel and landing page were already built, so I just answered a few setup questions about the app name and database. After installation, I ran pnpm dev, and the server launched with a blank website ready for customization.

While both CMSs required some setup, Payload streamlined the process with built-in configurations, reducing the number of manual steps compared to Contentful.

Development Workflow

Once the CMS was running, the next step was integrating it into an actual development workflow.

• Contentful: Development with Contentful required installing the Delivery API and rich text renderer libraries. I built a main frontend component to retrieve data by field ID or slug. Then, I rendered the title and the rich text content using the rich text renderer. Additional work was needed to fetch and display assets and create a structured navigation system.

• Payload: In Payload, customization was more direct. I created a Yakuman collection under src/collections, defining the structure in code. I then imported this collection into src/payload-config.ts. To handle relationships, I modified src/fields/link.ts to include references to Yakuman. Finally, I ran payload generate:types to ensure the schema was correctly structured.

The code-first approach of Payload made customization more seamless, avoiding the manual UI-based configurations required in Contentful.

Deployment Challenges

Setting up a CMS is one thing, but getting it live and working in production is another challenge entirely.

• Contentful: Deploying with Contentful involved using a static site generator, setting up GitHub Actions for CI/CD, and ensuring API keys were correctly restricted to specific origins. Contentful’s webhook system allowed automatic updates when new content was published. Migrations were handled manually through CLI tools.

• Payload: Deploying Payload to Vercel required more manual work. I installed the NeonDB plugin to ensure my database schema matched production. After pushing the project to GitHub and importing it into Vercel, I had to manually run database migrations via CLI. Additionally, I uploaded media assets to a blob storage service and adjusted environment variables.

While Contentful provided a smoother deployment experience with built-in automation, Payload's flexibility allowed for more control, albeit with a steeper learning curve.

Handling Data and Rich Text

Structured data is crucial in a CMS. How well each system handles content affects ease of use.

• Contentful: Handling rich text required using the Contentful rich text renderer to convert structured content into HTML. Custom handlers were needed for embeds and links.

• Payload: Payload’s pre-configured RichText component made rendering content much easier. It also supported singletons (known as “Globals”), simplifying global site content like headers and footers.

Payload’s built-in RichText handling simplified the process significantly, whereas Contentful required additional setup to handle rich content efficiently.

Conclusion

My experience overall getting spun up with Payload CMS was positive. Having a readymade site that I could tinker with to turn into a custom CMS site, with no spin-up required other than having a database already running and picking an admin password, removed some hurdles that I'm so used to that their absence was notable.

Lessons learned

• The easiest thing was getting started. If all I wanted was a website, I could have saved myself doing anything to the object model and just used the readymade Pages and Posts collections.

• The hardest part was making the transition from local dev to a cloud-hosted production build. It made sense in the end, but I had never before deployed to Vercel so it was all a learning experience.

• There are still open questions about how to make the production site adapt to new data without doing full redeployments, and how to enable some basic object creating through the site without using the admin panel. I would like to have an "I achieved this" button if I'm logged in, but I haven't gotten far enough to learn how to do that yet.

How Payload CMS was the most helpful

• Having a comprehensive site set up through create-payload-app

• Putting things in consistent places in the source tree. Though the frontend is distributed across several folders, the API is mostly contained in collections and fields, and the configuration is just a couple of files.

• The collection format pulls double duty to define the model data and configure the admin panel. It's surprisingly convenient.

• Allowing singleton data for things which are consistent throughout the application

Final Thoughts

Payload CMS offers a robust, flexible, and developer-friendly approach to managing content. Its code-first methodology ensures version control and eliminates many of the pitfalls associated with traditional click-driven CMS management. If you're looking for a CMS that puts developers first, allows self-hosting, and integrates seamlessly with modern frameworks, Payload is worth exploring.

Ready to try it for yourself? Let us know what you think on our Discord.