payload

Payload CMS

Open-source, Next.js-native headless CMS with full TypeScript support. Code-first configuration, self-hosted, with REST and GraphQL APIs.

Quick Start

npx create-payload-app@latest my-app
cd my-app
npm run dev

Opens admin at http://localhost:3000/admin.

Project Structure

my-app/
  app/                    # Next.js app directory
    (payload)/           # Payload admin routes
  collections/           # Content type definitions
  payload.config.ts      # Main configuration
  payload-types.ts       # Generated types

Configuration

// payload.config.ts
import { buildConfig } from 'payload';
import { mongooseAdapter } from '@payloadcms/db-mongodb';
// or: import { postgresAdapter } from '@payloadcms/db-postgres';

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

export default buildConfig({
  admin: {
    user: Users.slug,
  },
  collections: [Users, Posts, Media],
  db: mongooseAdapter({
    url: process.env.MONGODB_URI!,
  }),
  typescript: {
    outputFile: 'payload-types.ts',
  },
  secret: process.env.PAYLOAD_SECRET!,
});

Collections (Content Types)

// collections/Posts.ts
import { CollectionConfig } from 'payload';

export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
    defaultColumns: ['title', 'status', 'publishedAt'],
  },
  access: {
    read: () => true,  // Public read
    create: ({ req }) => !!req.user,  // Authenticated only
    update: ({ req }) => !!req.user,
    delete: ({ req }) => !!req.user,
  },
  versions: {
    drafts: true,
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      unique: true,
      admin: {
        position: 'sidebar',
      },
      hooks: {
        beforeValidate: [
          ({ value, data }) => value || data?.title?.toLowerCase().replace(/\s+/g, '-'),
        ],
      },
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
    },
    {
      name: 'publishedAt',
      type: 'date',
      admin: {
        position: 'sidebar',
      },
    },
    {
      name: 'status',
      type: 'select',
      options: [
        { label: 'Draft', value: 'draft' },
        { label: 'Published', value: 'published' },
      ],
      defaultValue: 'draft',
      admin: {
        position: 'sidebar',
      },
    },
    {
      name: 'content',
      type: 'richText',
    },
    {
      name: 'featuredImage',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'categories',
      type: 'relationship',
      relationTo: 'categories',
      hasMany: true,
    },
  ],
};

Field Types

// Text
{ name: 'title', type: 'text', required: true }

// Textarea
{ name: 'excerpt', type: 'textarea' }

// Rich Text (Lexical)
{ name: 'content', type: 'richText' }

// Number
{ name: 'price', type: 'number', min: 0 }

// Email
{ name: 'email', type: 'email' }

// Date
{ name: 'publishedAt', type: 'date' }

// Checkbox
{ name: 'featured', type: 'checkbox', defaultValue: false }

// Select
{
  name: 'status',
  type: 'select',
  options: [
    { label: 'Draft', value: 'draft' },
    { label: 'Published', value: 'published' },
  ],
}

// Radio
{
  name: 'type',
  type: 'radio',
  options: ['video', 'article', 'podcast'],
}

// Relationship
{
  name: 'author',
  type: 'relationship',
  relationTo: 'users',
}

// Upload
{
  name: 'image',
  type: 'upload',
  relationTo: 'media',
}

// Array (repeatable)
{
  name: 'gallery',
  type: 'array',
  fields: [
    { name: 'image', type: 'upload', relationTo: 'media' },
    { name: 'caption', type: 'text' },
  ],
}

// Group (nested object)
{
  name: 'meta',
  type: 'group',
  fields: [
    { name: 'title', type: 'text' },
    { name: 'description', type: 'textarea' },
  ],
}

// Blocks (flexible content)
{
  name: 'layout',
  type: 'blocks',
  blocks: [HeroBlock, ContentBlock, CTABlock],
}

Blocks

// blocks/Hero.ts
import { Block } from 'payload';

export const HeroBlock: Block = {
  slug: 'hero',
  labels: {
    singular: 'Hero',
    plural: 'Heroes',
  },
  fields: [
    { name: 'heading', type: 'text', required: true },
    { name: 'subheading', type: 'text' },
    { name: 'image', type: 'upload', relationTo: 'media' },
    {
      name: 'cta',
      type: 'group',
      fields: [
        { name: 'label', type: 'text' },
        { name: 'link', type: 'text' },
      ],
    },
  ],
};

Access Control

export const Posts: CollectionConfig = {
  slug: 'posts',
  access: {
    // Function-based access
    read: ({ req }) => {
      // Published posts are public
      if (!req.user) {
        return { status: { equals: 'published' } };
      }
      // Logged in users see all
      return true;
    },

    create: ({ req }) => !!req.user,

    update: ({ req }) => {
      if (!req.user) return false;
      // Admins can update all
      if (req.user.role === 'admin') return true;
      // Authors can only update own posts
      return {
        author: { equals: req.user.id },
      };
    },

    delete: ({ req }) => req.user?.role === 'admin',
  },
};

Hooks

export const Posts: CollectionConfig = {
  slug: 'posts',
  hooks: {
    beforeChange: [
      async ({ data, req, operation }) => {
        if (operation === 'create') {
          data.author = req.user?.id;
        }
        return data;
      },
    ],

    afterChange: [
      async ({ doc, operation }) => {
        if (operation === 'create') {
          // Send notification, revalidate cache, etc.
          await revalidatePath('/posts');
        }
      },
    ],

    beforeRead: [
      async ({ doc, req }) => {
        // Transform document before returning
        return doc;
      },
    ],
  },
  fields: [/* ... */],
};

REST API

Auto-generated at /api/{collection}.

// Get all posts
const response = await fetch('/api/posts');
const { docs, totalDocs, page, limit } = await response.json();

// Get single post
const post = await fetch('/api/posts/123').then(r => r.json());

// Query with parameters
const params = new URLSearchParams({
  where: JSON.stringify({
    status: { equals: 'published' },
    publishedAt: { less_than: new Date().toISOString() },
  }),
  sort: '-publishedAt',
  limit: '10',
  page: '1',
  depth: '2',
});

const filtered = await fetch(`/api/posts?${params}`).then(r => r.json());

Query Operators

// Equals
{ field: { equals: 'value' } }

// Not equals
{ field: { not_equals: 'value' } }

// Greater/less than
{ field: { greater_than: 100 } }
{ field: { less_than: 100 } }
{ field: { greater_than_equal: 100 } }
{ field: { less_than_equal: 100 } }

// Contains (string)
{ field: { contains: 'text' } }

// In array
{ field: { in: ['a', 'b', 'c'] } }

// Not in array
{ field: { not_in: ['x', 'y'] } }

// Exists
{ field: { exists: true } }

// Logical operators
{
  or: [
    { status: { equals: 'published' } },
    { featured: { equals: true } },
  ],
}

{
  and: [
    { status: { equals: 'published' } },
    { category: { equals: 'tech' } },
  ],
}

GraphQL API

Available at /api/graphql.

query {
  Posts(
    where: { status: { equals: published } }
    sort: "-publishedAt"
    limit: 10
  ) {
    docs {
      id
      title
      slug
      author {
        name
      }
    }
    totalDocs
  }
}

Local API (Server-Side)

Use in Server Components, API routes, or hooks.

import { getPayload } from 'payload';
import config from '@payload-config';

const payload = await getPayload({ config });

// Find many
const posts = await payload.find({
  collection: 'posts',
  where: {
    status: { equals: 'published' },
  },
  sort: '-publishedAt',
  limit: 10,
  depth: 2,
});

// Find one
const post = await payload.findByID({
  collection: 'posts',
  id: '123',
  depth: 2,
});

// Create
const newPost = await payload.create({
  collection: 'posts',
  data: {
    title: 'New Post',
    content: '...',
  },
});

// Update
const updated = await payload.update({
  collection: 'posts',
  id: '123',
  data: {
    title: 'Updated Title',
  },
});

// Delete
await payload.delete({
  collection: 'posts',
  id: '123',
});

TypeScript

Types are auto-generated to payload-types.ts.

import { Post, User } from './payload-types';

// Fully typed
const posts: Post[] = await payload.find({
  collection: 'posts',
});

posts.forEach((post: Post) => {
  console.log(post.title);  // TypeScript knows this exists
});

Next.js Integration

// app/posts/page.tsx
import { getPayload } from 'payload';
import config from '@payload-config';

export default async function PostsPage() {
  const payload = await getPayload({ config });

  const { docs: posts } = await payload.find({
    collection: 'posts',
    where: { status: { equals: 'published' } },
    sort: '-publishedAt',
  });

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <a href={`/posts/${post.slug}`}>{post.title}</a>
        </li>
      ))}
    </ul>
  );
}

// app/posts/[slug]/page.tsx
import { getPayload } from 'payload';
import config from '@payload-config';
import { notFound } from 'next/navigation';

export async function generateStaticParams() {
  const payload = await getPayload({ config });
  const { docs } = await payload.find({ collection: 'posts' });

  return docs.map((post) => ({ slug: post.slug }));
}

export default async function PostPage({ params }: { params: { slug: string } }) {
  const payload = await getPayload({ config });

  const { docs } = await payload.find({
    collection: 'posts',
    where: { slug: { equals: params.slug } },
    depth: 2,
  });

  if (!docs[0]) notFound();

  const post = docs[0];

  return (
    <article>
      <h1>{post.title}</h1>
      {/* Render content */}
    </article>
  );
}

Media Collection

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

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    staticDir: 'public/media',
    imageSizes: [
      {
        name: 'thumbnail',
        width: 400,
        height: 300,
        position: 'centre',
      },
      {
        name: 'card',
        width: 768,
        height: 1024,
        position: 'centre',
      },
    ],
    mimeTypes: ['image/*'],
  },
  fields: [
    { name: 'alt', type: 'text', required: true },
    { name: 'caption', type: 'text' },
  ],
};

Globals (Singletons)

// globals/Settings.ts
import { GlobalConfig } from 'payload';

export const Settings: GlobalConfig = {
  slug: 'settings',
  access: {
    read: () => true,
  },
  fields: [
    { name: 'siteName', type: 'text', required: true },
    { name: 'siteDescription', type: 'textarea' },
    {
      name: 'navigation',
      type: 'array',
      fields: [
        { name: 'label', type: 'text' },
        { name: 'link', type: 'text' },
      ],
    },
  ],
};

// Usage
const settings = await payload.findGlobal({ slug: 'settings' });

Authentication

// Login
const user = await payload.login({
  collection: 'users',
  data: {
    email: 'user@example.com',
    password: 'password',
  },
});

// Current user (in hooks/access control)
const user = req.user;

// Logout
await payload.logout({
  collection: 'users',
});

Deployment

# Build
npm run build

# Start production
npm run start

Deploy to:

• Vercel: One-click with Neon database
• Cloudflare: Workers + D1 + R2
• Self-hosted: Any Node.js host

Best Practices

1. Use Local API in Server Components for performance
2. Define access control for each collection
3. Use hooks for side effects (revalidation, notifications)
4. Generate types after schema changes: npm run generate:types
5. Use drafts for preview functionality
6. Configure image sizes to match your frontend needs