payloadcms-3-84-1 - SKILL.md Agent Skill

name: payloadcms-3-84-1 description: Payload CMS headless CMS toolkit including collections, fields, access control, authentication, custom components, plugin API, and Local API operations. Use when building content management systems, creating admin interfaces, implementing role-based access control, developing custom React components, or integrating with Next.js applications using TypeScript-first patterns.

Payload CMS 3.84.1

Overview

Payload is the open-source, fullstack Next.js framework that gives you instant backend superpowers. It installs directly into your existing /app folder, providing a full TypeScript backend and admin panel. Use it as a headless CMS or for building powerful applications. Payload 3.x replatformed the Admin Panel from a React Router SPA onto the Next.js App Router with full React Server Components support, completely separating core logic from HTTP and rendering layers.

Key capabilities:

Next.js native — runs inside your /app folder, no separate server
TypeScript-first — automatic type generation for all data models
Local API — query the database directly in server components without REST/GraphQL
Built-in auth — user management with JWT, API keys, and custom strategies
Versions and drafts — document versioning with autosave and scheduled publishing
Localization — multi-language content with fallback support
Block-based layout builder — composable content blocks for flexible page design
Lexical rich text editor — extensible WYSIWYG editor with custom features and view override system
Granular access control — collection, field, and document-level permissions
Extensive hooks system — document and field-level hooks for every operation
HTTP-only cookies, CSRF protection — enterprise-grade security by default
Expanded plugin API — definePlugin helper with opt-in execution ordering, cross-plugin discovery via slug-keyed plugins map, and module augmentation for type-safe plugin options
Profiling utilities — built-in performance analysis tools
Custom collection views — client components can be used as custom collection views
MCP plugin — support for server instructions and external plugin extension

When to Use

Building a headless CMS with a customizable React admin panel
Creating content-driven websites with Next.js App Router
Implementing role-based access control with fine-grained permissions
Building applications that need built-in authentication and user management
Creating block-based page builders or content management interfaces
Integrating versioning, drafts, and scheduled publishing workflows
Working with multi-language content requiring localization
Extending the admin UI with custom React Server Components
Building REST APIs or GraphQL endpoints on top of typed data models
Developing plugins with the new definePlugin helper for type-safe plugin options
Building custom collection views with client components

Core Concepts

Collections are the primary data model — similar to database tables. Each collection defines a slug, fields, access control, hooks, and admin UI configuration. Collections can enable authentication (auth: true), file uploads (upload: true), or versioning (versions: { drafts: true }).

Globals are singleton documents for site-wide content like headers, footers, and settings. Unlike collections, globals have no list view — only a single editable document.

Fields define the data shape within collections and globals. Payload supports text, number, email, textarea, code, date, point, radio, checkbox, select, richText, upload, relationship, join, group, row, tabs, collapsible, array, blocks, hidden, and json field types. Fields support validation, hooks, access control, localization, and conditional visibility.

Access Control operates at three levels: collection-level (create/read/update/delete), field-level (read/write per field), and document-level (returning a Where query to filter visible documents). Access functions receive the request context including the authenticated user.

Hooks run at every stage of the document lifecycle: beforeValidate, beforeChange, afterChange, beforeRead, afterRead, beforeDelete, afterDelete, and field-level hooks (beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate). Hooks can transform data, enforce business rules, trigger side effects, and integrate with external services.

The Payload Config (payload.config.ts) is the central configuration file defining collections, globals, database adapter, admin panel settings, plugins, custom endpoints, email adapter, localization, and more. It uses buildConfig() from the payload package.

The definePlugin Helper (new in 3.83) introduces opt-in execution ordering, cross-plugin discovery via a slug-keyed plugins map, and module augmentation for type-safe plugin options. The existing (config) => config contract remains unchanged.

import { definePlugin } from 'payload'

export const seoPlugin = definePlugin<SEOPluginOptions>({
  slug: 'plugin-seo',
  order: 10,
  plugin: ({ config, plugins, collections, generateTitle }) => ({
    ...config,
    // access to other plugins via slug-keyed map
    seoConfig: plugins['plugin-other']?.options,
  }),
})

Project Structure

A typical Payload project:

my-project/
├── src/
│   ├── app/
│   │   └── (payload)/
│   │       ├── admin/    # Admin panel routes (auto-generated)
│   │       └── api/      # API routes (auto-generated)
│   ├── collections/
│   │   ├── Users.ts
│   │   ├── Media.ts
│   │   └── Pages.ts
│   ├── globals/
│   │   ├── Header.ts
│   │   └── Footer.ts
│   ├── blocks/
│   │   ├── Content/
│   │   └── MediaBlock/
│   ├── access/
│   │   ├── authenticated.ts
│   │   └── authenticatedOrPublished.ts
│   ├── hooks/
│   │   └── populatePublishedAt.ts
│   ├── payload.config.ts
│   └── payload-types.ts  # auto-generated types
├── package.json
└── tsconfig.json

Quick Start

Create a new project with the blank template:

npx create-payload-app@latest my-project
cd my-project
pnpm dev

Or use the website template for a full-featured starter:

npx create-payload-app@latest -t website

Usage Examples

Minimal Payload Config

// payload.config.ts
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import path from 'path'
import { buildConfig } from 'payload'
import { fileURLToPath } from 'url'
import sharp from 'sharp'

import { Users } from './collections/Users'
import { Media } from './collections/Media'

const filename = fileURLToPath(import.meta.url)
const dirname = path.dirname(filename)

export default buildConfig({
  admin: {
    user: Users.slug,
    importMap: {
      baseDir: path.resolve(dirname),
    },
  },
  collections: [Users, Media],
  editor: lexicalEditor(),
  secret: process.env.PAYLOAD_SECRET || '',
  typescript: {
    outputFile: path.resolve(dirname, 'payload-types.ts'),
  },
  db: mongooseAdapter({
    url: process.env.DATABASE_URL || '',
  }),
  sharp,
  plugins: [],
})

Collection with Auth

// collections/Users.ts
import type { CollectionConfig } from 'payload'

export const Users: CollectionConfig = {
  slug: 'users',
  admin: {
    useAsTitle: 'email',
  },
  auth: true,
  fields: [
    // Email and password fields added automatically
  ],
}

Collection with Uploads

// collections/Media.ts
import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  access: {
    read: () => true,  // public access
  },
  fields: [
    {
      name: 'alt',
      type: 'text',
      required: true,
    },
  ],
  upload: true,
}

Access Control Functions

// access/authenticated.ts
import type { AccessArgs } from 'payload'
import type { User } from '@/payload-types'

export const authenticated = ({ req: { user } }: AccessArgs<User>) => {
  return Boolean(user)
}

// access/authenticatedOrPublished.ts
import type { Access } from 'payload'

export const authenticatedOrPublished: Access = ({ req: { user } }) => {
  if (user) return true
  return { _status: { equals: 'published' } }
}

Using the Local API in Server Components

import { getPayload } from 'payload'
import configPromise from '@/payload.config'

export async function getPosts() {
  const payload = await getPayload({ config: configPromise })
  const posts = await payload.find({
    collection: 'posts',
    where: { _status: { equals: 'published' } },
    sort: '-publishedAt',
  })
  return posts.docs
}

Using definePlugin (New in 3.83)

import { definePlugin } from 'payload'

type MyPluginOptions = {
  customField?: string
}

export const myPlugin = definePlugin<MyPluginOptions>({
  slug: 'my-plugin',
  order: 5,
  plugin: ({ config }) => ({
    ...config,
    collections: [
      ...(config.collections || []),
      {
        slug: 'my-collection',
        fields: [{ name: 'data', type: 'text' }],
      },
    ],
  }),
})

Advanced Topics

Collections and Fields: Deep dive into all field types, validation, relationships, joins, blocks, arrays, and rich text configuration → Collections and Fields

Access Control and Authentication: Role-based permissions, custom auth strategies, API keys, JWT configuration, and field-level access → Access Control and Authentication

Hooks and Lifecycle: Document hooks, field hooks, before/after operation patterns, and integration with external services → Hooks and Lifecycle

Local API and Queries: The Where query system, depth/population, select/projection, pagination, sorting, joins, and transactions → Local API and Queries

Versions, Drafts, and Localization: Document versioning, autosave drafts, scheduled publishing, multi-language content, and fallback locales → Versions Drafts and Localization

Admin Panel Customization: Custom React components, views, tabs, live preview, dashboard widgets, custom collection views with client components, and theme configuration → Admin Panel Customization

Database Adapters and Plugins: MongoDB, Postgres, SQLite, Drizzle ORM adapter patterns with uuidv7 support, storage adapters with composite prefixes, definePlugin helper, MCP plugin, and official plugins → Database Adapters and Plugins