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
- Payload is a TypeScript‑first, MIT‑licensed CMS that you configure in code and host yourself.
- The schema is a file — collections, fields, access rules and hooks are all part of your repository.
- It generates REST and GraphQL automatically, plus a Local API that skips HTTP entirely.
- With Astro it is a clean split: Payload serves content, Astro prerenders pages at build time.
- It costs you operations: a Node service, a database and someone to look after both.
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
- Product teams already on TypeScript who want content and code in one repository, reviewed in one pull request.
- Projects with real access rules — editors who see only their locale, clients who see only their own records.
- Teams that need custom endpoints next to the content API, because the CMS runs in the same process as their backend code.
- Agencies that hand over a codebase rather than a SaaS subscription.
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:
- Types come from the CMS. Run
payload generate:typesand importPostfrompayload-types.ts. A field renamed in the config breaksastro checkbefore it breaks the site. - Drafts go through a second path. For preview, add an on‑demand route that requests the draft version with an authenticated token; everything public stays static.
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
- Ownership. MIT licence, your database, your server, your repository.
- One language. Config, hooks, access control and the front‑end are all TypeScript.
- Typing that survives refactors. Generated types track the schema.
- Local API. Server‑side code can query the database directly — no HTTP hop.
- Real editorial features. Drafts, versions, live preview, localisation, uploads with image resizing.
Weaknesses
- You run it. Deployments, backups, database upgrades and monitoring are yours.
- Payload 3 brings Next.js along. The admin is a Next.js app, so a static Astro site now has a Node service beside it.
- Smaller plugin ecosystem than WordPress or Strapi; expect to write the integrations you need.
- Schema changes are code changes. Great for review, slower for a marketer who wants a new field now.
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
Founder, SEO & analytics
Runs Take the Space. Specialises in technical SEO, measurable analytics setups and AI search visibility.