|
|
| Line 1: |
Line 1: |
| {{Community_Page}}
| |
| {{CMS_Infobox | | {{CMS_Infobox |
| | name = Payload CMS | | | name = Payload CMS |
| | status = Community | | | developer = Payload CMS Inc. |
| | type = Headless CMS / Application Framework | | | type = Headless CMS / Application Framework |
| | license = MIT | | | license = MIT License |
| | language = TypeScript / JavaScript (Node.js) | | | language = TypeScript / Node.js |
| | database = MongoDB / PostgreSQL / SQLite | | | released = 2022 |
| | latest_ver = 3.x | | | latest_version = 3.x |
| | release_date = 2021
| | | website = https://payloadcms.com |
| | website = https://payloadcms.com | | | github = https://github.com/payloadcms/payload |
| | github = https://github.com/payloadcms/payload | | | stars = 29,000+ |
| | demo = https://payloadcms.com | |
| }} | | }} |
|
| |
|
| '''Payload CMS''' (often simply referred to as '''Payload''') is an open-source, code-first [[Headless CMS|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 CMS''' is a modern, TypeScript-first, open-source headless CMS designed to give developers complete control over their content architecture. |
| | |
| Payload automatically generates fully typed [[REST API|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 == | | == 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.
| | Payload CMS was officially released in 2022. Payload 3.0 brought native Next.js integration — making Payload the first headless CMS that runs inside a Next.js application as route handlers, with no separate server needed. |
| | | Payload is completely open source (MIT license) and self-hosted. |
| 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 == | | == Key Features == |
| | * '''TypeScript-native''' — Fully typed configuration, generated types from your schema |
| | * '''Next.js Native''' — Runs as Next.js route handlers inside your app |
| | * '''Auto-generated Admin UI''' — Extensible admin panel generated from your schema |
| | * '''Rich Text (Lexical)''' — Modern block-based rich text editor |
|
| |
|
| === Code-First Schema Definition === | | == Installation == |
| 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.
| | Payload is installed via Node package manager. You can scaffold a new project using the official template tool or install it directly into an existing Next.js application. |
| | |
| <syntaxhighlight lang="typescript">
| |
| 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,
| |
| },
| |
| ],
| |
| };
| |
| </syntaxhighlight>
| |
| | |
| === 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:
| |
| | |
| <syntaxhighlight lang="typescript">
| |
| 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,
| |
| });
| |
| </syntaxhighlight>
| |
| | |
| 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:
| |
| | |
| <syntaxhighlight lang="typescript">
| |
| access: {
| |
| read: ({ req: { user } }) => {
| |
| if (user?.role === 'admin') return true;
| |
| return {
| |
| status: {
| |
| equals: 'published',
| |
| },
| |
| };
| |
| },
| |
| update: ({ req: { user } }) => user?.role === 'admin',
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === 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.
| |
| | |
| {| class="wikitable" style="width:100%;"
| |
| ! 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.
| |
| | |
| {| class="wikitable sortable" style="width:100%;"
| |
| ! 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 === | | == API Reference == |
| Payload Cloud is a managed Platform-as-a-Service designed specifically for Payload applications. It automates DevOps infrastructure provisioning: | | Payload automatically generates REST and GraphQL endpoints for all configured collections. It also provides a Local API, allowing you to query data directly from your Next.js server components with zero network latency. |
| * 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 == | | == Pricing == |
| | Payload CMS is '''100% free and open source'''. |
|
| |
|
| {| class="wikitable sortable" style="width:100%;" | | == Pros & Cons == |
| ! Feature / Aspect !! Payload CMS !! Strapi !! Directus !! Contentful | | {| class="wikitable" |
| |-
| | ! ✅ Pros !! ❌ Cons |
| | '''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) | | | Runs natively inside Next.js || Younger ecosystem |
| |- | | |- |
| | '''License''' || MIT || MIT / Commercial || BSL 1.1 / Commercial || Proprietary | | | Fully TypeScript-native || Fewer community plugins |
| |- | | |- |
| | '''Next.js Native''' || Yes (Payload 3.0+) || No (External API) || No (External API) || No (External API) | | | Local API for zero-latency queries || Specific database engines required |
| |} | | |} |
|
| |
|
| == External links == | | == External Links == |
| * [https://payloadcms.com Official Payload CMS Website] | | * [https://payloadcms.com Official Website] |
| * [https://github.com/payloadcms/payload Payload CMS GitHub Repository]
| | * [https://payloadcms.com/docs Documentation] |
| * [https://payloadcms.com/docs Payload Official Documentation] | |
| * [https://payloadcms.com/community Payload Discord & Community]
| |
| * [https://payloadcms.com/blog Payload CMS Blog & Announcements]
| |
|
| |
|
| [[Category:CMS_Platforms]] | | [[Category:CMS_Platforms]] |
| [[Category:Headless_CMS]] | | [[Category:Headless_CMS]] |
| [[Category:Open_Source_CMS]] | | [[Category:Open_Source_CMS]] |
| [[Category:TypeScript]]
| |
