Introduction to PayloadCMS
About this guide
This guide is aimed at developers who have used Next.js and TypeScript. It explains PayloadCMS through 7 chapters, with the goal that readers who want to "run a CMS on my own database, with my own code" can decide whether to adopt it for their project after finishing the series.
What this guide focuses on
- Concept-first, with short code excerpts: rather than a runnable tutorial, each feature is shown with the minimum code needed to convey "what it can do and how you write it"
- Next.js co-location (3.x) as the central theme: a full chapter is dedicated to the headline feature of PayloadCMS
- Postgres as the default: the Postgres adapter, marked stable in 2024, is the baseline (Mongo / SQLite are mentioned briefly)
- OSS / self-hosted perspective: design decisions and operational tips are framed throughout from a "self-host" standpoint
- Verification point-in-time: the main claims in this guide were checked against the official docs as of Payload v3.85 (July 2026); features added later may not be reflected
Guide structure
Chapters
| Chapter | Theme | Overview |
|---|---|---|
| 01 What is PayloadCMS / Why now | Big picture | Position as a Headless CMS / what changed in 3.x / the context of the Figma acquisition and OSS / comparison with other CMSes |
| 02 Core Concepts | Config-first | payload.config.ts as the heart of the design / when to use Collections vs Globals |
| 03 Data Modeling | Fields / Lexical | Field type catalog / Blocks / Lexical Rich Text / Localization / Versions & Drafts |
| 04 Security & Lifecycle | Auth / Hooks | Built-in Users and JWT / function-based Access Control / Hooks lifecycle |
| 05 APIs | Three-layer API | Local API / REST / GraphQL — how they relate and when to use each / generated types |
| 06 Next.js Integration ★ | Co-location | Route groups / Local API from Server Components / Live Preview / Draft Preview |
| 07 Admin / Media / Deploy | Operations | Admin UI customization / Plugins / Media (uploads + S3) / Postgres adapter / Migration / Jobs Queue / Vercel deployment |
★ = the headline chapter of this series. It dives deep into the Next.js co-location architecture introduced in 3.x.
Who this guide is for
- Developers comfortable with Next.js (App Router) and TypeScript
- Anyone who wants to run a Headless CMS on their own infrastructure and their own database
- Teams considering moving away from Strapi / Sanity / Contentful to PayloadCMS
Prerequisites
| Required | Knowledge |
|---|---|
| Required | Basic TypeScript / basics of the Next.js App Router |
| Recommended | Basic Postgres (or any RDB) operations / a sense of REST API design |
| Nice to have | Some hands-on experience with at least one Headless CMS (Strapi / Sanity / Contentful, etc.) |
How to read this guide
- New to PayloadCMS: read from chapter 01, settle the concepts, then make sense of the implementation in chapter 06 (Next.js co-location)
- Familiar with Next.js, just deciding whether to adopt: read chapter 01 (why now) and chapter 06 (co-location) first, then dip into chapters 02–05 as needed
- As a reference: jump straight to the relevant row in the chapter table above
Out of scope
- An introduction to React itself, or to the Next.js App Router (the official docs are recommended)
- A deep dive into the PayloadCMS enterprise features (SSO / Multi-Tenancy, etc.); these are only mentioned in passing in chapter 07
- Deploy walkthroughs for a runnable sample app (the official templates already cover this; this guide focuses on the design decisions)
References
- Official docs: https://payloadcms.com/docs/getting-started/what-is-payload
- 3.0 release post: Payload 3.0: The first CMS that installs directly into any Next.js app
- GitHub: payloadcms/payload
Let's start with Chapter 01 — What is PayloadCMS / Why now.