Yuri Osipov · Founder, SEO & analytics

Payload CMS: the CMS that lives in your codebase

Most CMS products ask your team to adapt to their data model. Payload asks you to write it. That single decision explains both why developers like it and why it is not the right answer for every client.

In short

What Payload actually is

Payload is a headless CMS written in TypeScript. You install it as a dependency, describe your content in payload.config.ts, and get three things at once: an admin panel, a REST/GraphQL API, and generated TypeScript types.

// payload.config.ts
import { buildConfig } from 'payload'
import { postgresAdapter } from '@payloadcms/db-postgres'

export default buildConfig({
  collections: [
    {
      slug: 'posts',
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'slug', type: 'text', required: true, unique: true },
        { name: 'body', type: 'richText' },
      ],
    },
  ],
  db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URL } }),
})

That file is the product. Fields can be nested, grouped into blocks, localised, validated, and protected by access functions that receive the current user. Nothing in the content model is hidden behind a UI that only one person knows how to operate.

Who it fits

It fits less well when nobody on the team wants to own a server, or when the content team needs to publish in the next two days and the schema is still being designed.

How it connects to Astro

The integration is deliberately boring, which is the point. Payload exposes /api/<collection>; Astro fetches it at build time.

// src/lib/payload.ts
const CMS = import.meta.env.PAYLOAD_URL

export async function getPosts() {
  const res = await fetch(`${CMS}/api/posts?limit=100&depth=1`)
  if (!res.ok) throw new Error(`Payload: ${res.status}`)
  return (await res.json()).docs
}

Then a normal Astro route turns that into pages:

export async function getStaticPaths() {
  const posts = await getPosts()
  return posts.map((post) => ({ params: { slug: post.slug }, props: { post } }))
}

Two details make this pleasant in practice:

Rich text is stored as a structured document, not raw HTML, so you map it to your own components instead of trusting whatever markup the editor produced. That is more work up front and a much better result after a redesign.

What editors get

The admin is plain React, not a page builder: a list of collections on the left, fields on the right, a preview panel if you wire one up. Editors who have used WordPress will recognise the rhythm in ten minutes. What they will not get is drag‑and‑drop layout freedom — the schema decides what a page can be, which is exactly why the front‑end stays predictable.

Strengths

Weaknesses

A note on that last point: it is a feature, not a bug, but it changes who can move fast. If your content team ships daily experiments, a UI‑driven content model may serve them better.

When to choose Payload

Choose it when the CMS is part of the product, not a separate appliance: when you need custom access rules, business logic near the content, or a content model that no off‑the‑shelf template would cover. Choose it when the team is comfortable operating a Node service and would rather debug their own code than a vendor’s black box.

Skip it when the site is a brochure with three editors and no backend needs — Keystatic will get you there in an afternoon, and Sanity will spare you the server entirely.

Summary

Payload is the option we reach for when a client wants a CMS they own, in a language their developers already speak. It is not the cheapest to operate and not the fastest to start; it is the one that stays understandable three years in.

Next: see how it compares with the rest in the headless CMS comparison for Astro, read the Sanity guide for the hosted alternative, or start from the headless CMS hub. If you want this built and handed over properly, that is what we do in web development.

Screenshots in this series are placeholders — we will replace them with our own, taken on real projects.

Yuri Osipov

Yuri Osipov

Founder, SEO & analytics

Runs Take the Space. Specialises in technical SEO, measurable analytics setups and AI search visibility.

All posts by the author →
Is Payload CMS free?
Yes. Payload is open source under the MIT licence, and you can run it on your own infrastructure without paying a licence fee. You pay for the server, the database and your own maintenance — and there is a hosted option if you prefer not to run it yourself.
Do I need Next.js to use Payload with Astro?
No, but you should know what you are deploying. Payload 3 ships its admin panel inside a Next.js application, so you run one Node service for the CMS and a separate Astro build for the public site. The front‑end stays Astro; Next.js only serves the admin and the API.
Which database does Payload use?
Payload supports PostgreSQL, MongoDB and SQLite through database adapters, configured in the same file as the rest of the CMS. Postgres is the common choice for production because backups, migrations and monitoring are well understood.
How do editors preview content before publishing?
Payload has drafts, versions and a live preview panel that can point at your Astro site. The usual setup runs the preview on an on‑demand route that fetches the draft version, while the public site keeps serving prerendered pages.
Can I move off Payload later?
Because the schema is code and the data sits in an ordinary database, exporting is straightforward — collections are tables, uploads are files on disk or object storage. The real lock‑in is the admin customisations you build, not the data.

Want a high‑performance website?

Let’s discuss how we can help your business grow.