Jump to content

Payload CMS

From ZelocoreCMS Wiki

🤝 Community Page — This page is maintained by the ZelocoreCMS community. Information may not reflect the latest official details. If you are the official CMS owner, claim your page to manage it officially.

Payload CMS
Status 🤝 Community
Type Headless CMS / Application Framework
License MIT
Language TypeScript / JavaScript (Node.js)
Database MongoDB / PostgreSQL / SQLite
Latest Version 3.x
Release Date 2021
Website Official Site
GitHub Repository

Payload CMS (often simply referred to as Payload) is an open-source, code-first headless Content Management System and application framework built natively with TypeScript, Node.js, and React. Designed primarily for developers, Payload offers an enterprise-grade content management architecture where data schemas, validation logic, access control rules, and admin dashboard customizations are defined entirely in standard TypeScript code rather than through drag-and-drop graphical user interfaces.

Payload automatically generates fully typed REST and GraphQL endpoints alongside a customizable React-based administration dashboard. A standout feature of Payload is its native Local API, which enables developers to query and mutate content directly within server-side Node.js and Next.js application code with zero network overhead and total end-to-end type safety. Released under the permissive MIT License, Payload is widely utilized to build high-performance web applications, enterprise portals, e-commerce platforms, and omnichannel content management solutions.

Overview

Traditional Content Management Systems like WordPress or Drupal manage content schemas through database GUI tools or web dashboards, often storing content structures as serialized blobs or dynamic configurations that are difficult to track in version control. In contrast, Payload adopts a **code-first philosophy**. In Payload, every content entity—termed a Collection or a Global—is declared as a TypeScript configuration object inside the project codebase.

This approach integrates content modeling into standard software development lifecycles. Content schemas can be version-controlled with Git, tested via continuous integration pipelines, reviewed in pull requests, and deployed predictably across local development, staging, and production environments.

Key Technical Pillars

  • Code-First Architecture: Schemas, field validations, and hooks are defined in TypeScript source code, eliminating database sync issues across environments.
  • TypeScript Native: Automatic type generation (`payload generate:types`) provides strict compile-time checking and autocomplete for database queries across the entire front-end and back-end application stack.
  • Local API Execution: Executes database operations directly inside the Node.js server context, bypassing HTTP requests and serialization overhead.
  • Database Agnostic Adapters: Native support for both document databases (MongoDB) and relational databases (PostgreSQL, SQLite) via an abstracted database adapter pattern.
  • Full-Stack Next.js Integration: In Payload v3.0, the core engine was refactored to run natively inside the Next.js App Router, enabling seamless deployment on serverless environments such as Vercel as well as traditional Node.js servers.

History

Payload was created in 2020 by James Mikrut, Dan Ribbens, and Elliot DeNolf, partners at the digital design and development agency TRBL based in Buffalo, New York. Having built complex web applications for global enterprise clients using various open-source and proprietary headless CMS products (including Strapi, Contentful, and Sanity.io), the founders grew frustrated by existing limitations—specifically poor TypeScript integration, complex GUI-driven schema migrations, vendor lock-in, and inefficient database querying mechanisms.

They set out to build a modern backend framework that combined the rapid developer experience of an object-relational mapping (ORM) library with the turnkey functionality of an enterprise headless CMS and administration dashboard.

Major Milestones

  • 2021: Public Launch (Payload 1.0): Payload was launched commercially as a developer-first headless CMS running on Node.js, Express, and MongoDB.
  • 2022: Transition to Open Source (MIT License): In response to explosive growth within the developer community, Payload transitioned from a proprietary/freemium model to a 100% free and open-source platform under the permissive MIT License.
  • 2023: Relational Database Support (PostgreSQL Adapter): Payload introduced a pluggable database architecture, launching official support for PostgreSQL and SQLite via Drizzle ORM alongside its original MongoDB adapter.
  • 2023: Launch of Payload Cloud: Payload announced **Payload Cloud**, a managed Platform-as-a-Service (PaaS) built on AWS infrastructure, offering automated GitHub deployments, managed databases, asset storage, and global CDN caching.
  • 2024: Payload 3.0 & Next.js Native Architecture: Payload released version 3.0, marking a major architectural evolution. Payload was completely rewritten to run natively within Next.js App Router, enabling single-repo full-stack Next.js applications and serverless cloud deployment.

Key Features

Code-First Schema Definition

In Payload, schemas are defined as plain JavaScript/TypeScript objects. Developers specify fields such as `text`, `number`, `richText`, `relationship`, `upload`, `array`, `blocks`, and `json`. Because schemas live in code, developers can utilize standard programming patterns, including module imports, environment variables, utility functions, and shared interfaces. 

import { CollectionConfig } from 'payload/types';

export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
    },
    {
      name: 'content',
      type: 'richText',
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
      required: true,
    },
  ],
};

End-to-End TypeScript Support

Payload is written entirely in TypeScript. The platform includes CLI tooling (`payload generate:types`) that parses collection and global configurations to automatically produce exact TypeScript interface definitions for all application data models. Front-end code consuming Payload APIs receives full autocompletion, type checking, and compile-time error detection.

Native Local API

While most headless CMS platforms rely exclusively on HTTP-based REST or GraphQL requests, Payload exposes a high-performance **Local API**. When Payload is embedded within a Node.js or Next.js application, developers can import the `payload` instance directly and call CRUD methods: 

import payload from 'payload';

// Querying database directly on the server without HTTP overhead
const posts = await payload.find({
  collection: 'posts',
  where: {
    status: {
      equals: 'published',
    },
  },
  limit: 10,
});

The Local API executes database queries directly through the configured database adapter, bypassing HTTP middleware, routing layers, and JSON stringification. It also supports skipping permission checks (`overrideAccess: true`) for administrative server processes.

REST & GraphQL Auto-Generation

Every collection and global registered in Payload automatically generates fully compliant RESTful endpoints and a GraphQL schema:

  • REST API: Exposes standard CRUD operations (`GET /api/posts`, `POST /api/posts`, `PATCH /api/posts/:id`, `DELETE /api/posts/:id`) featuring nested query parameters for filtering (`where`), sorting (`sort`), field selection (`select`), and relationship population (`depth`).
  • GraphQL API: Generates query and mutation schemas out of the box, accessible via an interactive GraphQL Playground route.

Granular Access Control

Payload features an expressive security framework operating at the collection, field, and document levels. Access control functions return a boolean (`true`/`false`) or a query constraint object (`where` clause) that restricts results at the database query level: 

access: {
  read: ({ req: { user } }) => {
    if (user?.role === 'admin') return true;
    return {
      status: {
        equals: 'published',
      },
    };
  },
  update: ({ req: { user } }) => user?.role === 'admin',
}

Customizable Admin UI & Rich Text

The administrative control panel is built using React and dynamically renders input interfaces based on registered collection fields.

  • Custom React Components: Developers can override or inject custom React components into any part of the admin panel (e.g., custom field inputs, dashboard widgets, view headers, navigation bars).
  • Rich Text Editing: Payload features native rich text editors built on Lexical (default in v3.0) and Slate. The editor converts rich text into structured JSON AST (Abstract Syntax Tree) data rather than raw HTML, ensuring clean data separation and rendering flexibility on front-end frameworks.

Architecture

Payload's architecture is structured around a central configuration file (`payload.config.ts`), separating the application core into modular subsystems: the HTTP server execution layer, the database adapter layer, and the React admin interface.

Node.js, Express & Next.js Core

Payload operates as an application framework embedded within Node.js environments.

  • Payload 1.x & 2.x Architecture: Ran as standard Express middleware or standalone Node.js HTTP servers.
  • Payload 3.0 Native Next.js Architecture: Refactored to integrate directly into the Next.js App Router. Route handlers, admin UI pages, and REST/GraphQL APIs are mounted as Next.js route segments. This enables unified deployment where front-end Next.js pages and back-end Payload CMS services co-exist in a single repository and execute within serverless edge/Node.js runtimes.

Database Abstraction Layer

Payload delegates database interaction to dedicated database adapters, preventing vendor lock-in and allowing organizations to select optimal storage engines:

  • MongoDB Adapter (`@payloadcms/db-mongodb`): Connects to MongoDB database clusters using official driver abstractions. Supports document embedding, flexible schemaless extensions, and MongoDB aggregation pipelines.
  • PostgreSQL Adapter (`@payloadcms/db-postgres`): Built on top of **Drizzle ORM**. Automatically manages relational SQL database schemas, migrations, join tables, foreign keys, and indexes.
  • SQLite Adapter (`@payloadcms/db-sqlite`): Enables lightweight, file-backed or in-memory relational storage suitable for local testing, edge runtimes, and low-cost server deployments.
Database Engine Adapter Package Relational / Document Primary Use Case
MongoDB `@payloadcms/db-mongodb` Document Store Large-scale content hubs, dynamic schemas
PostgreSQL `@payloadcms/db-postgres` Relational SQL Enterprise production, strict relational data
SQLite `@payloadcms/db-sqlite` Relational SQL Local development, testing, edge deployment

React-Based Admin Interface

The administrative dashboard is a React application built with server-side and client-side components. It communicates with the backend via internal Local API calls (when rendered server-side in Next.js) or REST/GraphQL APIs (when rendered client-side). The admin interface automatically handles authentication state, JWT storage, media file drops, localization toggles, and dynamic form rendering.

Extensibility

Payload provides extensive extension points allowing developers to build custom workflows and integrations.

Lifecycle Hooks

Payload exposes lifecycle hooks at the field, document, and collection levels. Hooks allow developers to run custom business logic before or after database actions:

  • `beforeValidate` / `beforeChange` / `afterChange`
  • `beforeRead` / `afterRead`
  • `beforeDelete` / `afterDelete`
  • `beforeLogin` / `afterLogin`

Lifecycle hooks are frequently used to send transactional emails (via Nodemailer or Resend), revalidate static front-end pages (e.g., calling Next.js `revalidatePath`), sync data with search indexes (Algolia, Meilisearch), or generate webhooks.

Custom Endpoints & Fields

Developers can attach custom REST HTTP endpoints directly to the Payload Express/Next.js application routing table. Additionally, custom field types can be created by pairing field configuration definitions with custom React input components.

Plugin Ecosystem

Payload includes an official plugin architecture. Plugins can modify existing configurations, add new collections, inject admin UI elements, and attach hooks automatically. Popular official plugins include:

  • SEO Plugin: Generates meta titles, descriptions, and open graph image previews in the admin panel.
  • Search Plugin: Automatically indexes collection documents into a centralized search collection for fast full-text searching.
  • Form Builder Plugin: Enables content editors to build custom forms with dynamic fields in the admin UI and capture user submissions.
  • Nested Docs Plugin: Enables hierarchical tree-structure relationships for categories and document pages.
  • Cloud Storage Plugins: Direct media upload integrations for AWS S3, Cloudflare R2, Azure Blob Storage, and Google Cloud Storage.

Payload Cloud vs Self-Hosted

Organizations evaluating Payload can choose between self-hosting the open-source core or utilizing Payload's fully managed cloud infrastructure.

Feature / Dimension Self-Hosted Payload Payload Cloud
Hosting Infrastructure Self-managed (AWS, Hetzner, Vercel, VPS, Docker) Fully managed cloud on AWS
Database Management Manual setup (MongoDB Atlas, Supabase, RDS) Managed PostgreSQL or MongoDB included
Media Asset Storage Custom S3 / CDN integration required Automated S3 storage & global CDN included
Deployment Model CI/CD pipelines, Docker, or git push Automatic git-push deployments from GitHub
Licensing Cost Free and Open Source (MIT) Paid monthly / annual subscription plans
Data Sovereignty 100% control over server region & compliance Cloud compliance standards (SOC2, GDPR)
Maintenance Overhead Server updates, security patches, backups Automated platform updates, scaling & backups

Self-Hosted Deployments

Because Payload is standard Node.js/TypeScript code, developers can self-host Payload applications anywhere Node.js runs:

  • Virtual Private Servers (VPS): Deployed on services like Hetzner, DigitalOcean, or Linode using process managers like PM2 or systemd behind reverse proxies (Nginx, Caddy).
  • Containerization (Docker): Packaged into lightweight Docker containers orchestrated via Docker Compose or Kubernetes.
  • Serverless Platforms: Deployed directly to Vercel, AWS Lambda, Railway, or Fly.io using Payload 3.0 Next.js integration.

Payload Cloud

Payload Cloud is a managed Platform-as-a-Service designed specifically for Payload applications. It automates DevOps infrastructure provisioning:

  • Connects directly to GitHub repositories for automatic build and deployment pipelines.
  • Provisions dedicated database instances (MongoDB or PostgreSQL).
  • Configures secure cloud media bucket storage backed by AWS S3 and Cloudflare CDN.
  • Provides staging environments, domain SSL certificate management, and continuous database backups.

Comparison with Other CMS Platforms

Feature / Aspect Payload CMS Strapi Directus Contentful
Architecture Model Code-First Headless GUI-First Headless SQL-First Wrapper Proprietary SaaS
Primary Language TypeScript / Node.js JavaScript / Node.js JavaScript / Node.js SaaS API
Schema Ownership TypeScript Config Code GUI & JSON Config Direct SQL Schema SaaS Web Dashboard
Database Options MongoDB, PostgreSQL, SQLite PostgreSQL, MySQL, SQLite Any SQL Database Proprietary Cloud DB
Local Server API Yes (Direct Node/Next API) Limited (Entity Service) Limited (SDK over HTTP) No (HTTP API Only)
License MIT MIT / Commercial BSL 1.1 / Commercial Proprietary
Next.js Native Yes (Payload 3.0+) No (External API) No (External API) No (External API)
Retrieved from "https://zelocorecms.org/index.php?title=Payload_CMS&oldid=53"