Payload CMS Integration

Payload CMS Integration for Content Management

Payload — an open-source headless CMS on Node.js. It differs from competitors in that it is part of the application itself: config is written in TypeScript and lives in the repository. No external dashboards, no vendor lock-in. It's not a service — it's a library you mount into Express or Next.js.

When Payload Makes Sense

The product is suitable when you need full control over data schema, custom authentication, or when you need to embed a CMS into an existing backend. Payload doesn't require separate hosting — it runs in the same place as your API.

Don't use it if your content management team is large and accustomed to cloud CMSes with guaranteed uptime — Contentful or Prismic would be simpler.

Project Structure

my-project/
├── src/
│   ├── payload.config.ts   # main config
│   ├── collections/        # content types
│   │   ├── Posts.ts
│   │   ├── Users.ts
│   │   └── Media.ts
│   ├── globals/            # singleton documents
│   │   └── SiteSettings.ts
│   └── server.ts

Collection Configuration

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

const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
    defaultColumns: ['title', 'status', 'publishedAt'],
  },
  access: {
    read: ({ req: { user } }) => {
      if (user) return true
      return { status: { equals: 'published' } }
    },
    create: ({ req: { user } }) => Boolean(user?.roles?.includes('editor')),
    update: ({ req: { user } }) => Boolean(user?.roles?.includes('editor')),
  },
  versions: {
    drafts: { autosave: true },
    maxPerDoc: 20,
  },
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'slug', type: 'text', unique: true, admin: { position: 'sidebar' } },
    {
      name: 'content',
      type: 'richText',
      editor: lexicalEditor({
        features: ({ defaultFeatures }) => [
          ...defaultFeatures,
          HTMLConverterFeature({}),
        ],
      }),
    },
    {
      name: 'featuredImage',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'status',
      type: 'select',
      options: ['draft', 'published'],
      defaultValue: 'draft',
      admin: { position: 'sidebar' },
    },
    {
      name: 'publishedAt',
      type: 'date',
      admin: { position: 'sidebar', date: { pickerAppearance: 'dayAndTime' } },
    },
  ],
}

export default Posts

Main Config

// src/payload.config.ts
import { buildConfig } from 'payload/config'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import Posts from './collections/Posts'
import Users from './collections/Users'
import Media from './collections/Media'

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  admin: {
    user: Users.slug,
    bundler: webpackBundler(),
  },
  editor: lexicalEditor({}),
  collections: [Posts, Users, Media],
  db: mongooseAdapter({ url: process.env.DATABASE_URI! }),
  // or PostgreSQL:
  // db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URI } }),
  upload: {
    limits: { fileSize: 10_000_000 },
  },
  localization: {
    locales: ['uk', 'en'],
    defaultLocale: 'uk',
    fallback: true,
  },
})

Payload supports MongoDB and PostgreSQL through official adapters. For PostgreSQL, migrations are generated automatically:

npx payload migrate:create
npx payload migrate

Next.js 14 Integration

Starting with Payload 2.x, mounting in Next.js App Router is supported:

// app/(payload)/admin/[[...segments]]/page.tsx
import { RootPage } from '@payloadcms/next/views'
import config from '@payload-config'

export default RootPage.bind(null, { config })

// app/(payload)/api/[...slug]/route.ts
import { REST_DELETE, REST_GET, REST_PATCH, REST_POST } from '@payloadcms/next/routes'
import config from '@payload-config'

export const GET = REST_GET.bind(null, config)
export const POST = REST_POST.bind(null, config)
export const PATCH = REST_PATCH.bind(null, config)
export const DELETE = REST_DELETE.bind(null, config)

This means — one next start, one process, one deployment.

Local API Requests

Payload provides Local API for server code — without HTTP overhead:

import payload from 'payload'
import config from '@payload-config'

await payload.init({ config })

const posts = await payload.find({
  collection: 'posts',
  where: {
    status: { equals: 'published' },
    publishedAt: { less_than_equal: new Date().toISOString() },
  },
  sort: '-publishedAt',
  limit: 10,
  depth: 2, // populate linked documents
})

REST API works in parallel and is accessible to external clients:

GET /api/posts?where[status][equals]=published&sort=-publishedAt&limit=10

Hooks and Extensions

Payload supports hooks at the collection level — before/after operations:

{
  slug: 'posts',
  hooks: {
    beforeChange: [
      async ({ data, operation }) => {
        if (operation === 'create') {
          data.slug = slugify(data.title)
        }
        return data
      },
    ],
    afterChange: [
      async ({ doc }) => {
        await revalidatePath(`/blog/${doc.slug}`)
      },
    ],
  },
}

Custom endpoints are added directly to the collection:

endpoints: [
  {
    path: '/:id/publish',
    method: 'post',
    handler: async (req, res) => {
      await payload.update({
        collection: 'posts',
        id: req.params.id,
        data: { status: 'published', publishedAt: new Date() },
      })
      res.json({ message: 'Published' })
    },
  },
],

Media and File Upload

const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    staticURL: '/media',
    staticDir: 'media',
    imageSizes: [
      { name: 'thumbnail', width: 400, height: 300, crop: 'centre' },
      { name: 'card', width: 768, height: 1024 },
      { name: 'hero', width: 1920, height: undefined },
    ],
    adminThumbnail: 'thumbnail',
    mimeTypes: ['image/*', 'application/pdf'],
  },
  fields: [{ name: 'alt', type: 'text' }],
}

For S3 — official @payloadcms/plugin-cloud-storage plugin with S3, GCS, or Azure adapters.

Timeline

Basic setup with 3–4 collections, localization, and Next.js integration: 5–7 days. If custom authentication, RBAC, complex hooks are needed — from 2 weeks.