Интеграция CMS Payload CMS для управления контентом

Headless CMS часто оказываются 'чёрным ящиком': вы не можете изменить логику админки, добавить кастомный эндпоинт или встроить аутентификацию без костылей. Payload решает эту проблему радикально — он живёт в вашем репозитории как обычная npm-библиотека. Мы используем Payload в продакшене на проектах с высокой нагрузкой и знаем все его подводные камни.

Почему Payload, а не Strapi или Contentful?

Payload — не сервис, не SaaS. Это npm-пакет, который монтируется в Express или Next.js. Вы не платите за лицензию и не привязаны к вендору. В отличие от Strapi, где кастомизация админки требует fork-репозитория, в Payload вы пишете конфиг на TypeScript и получаете полностью контролируемый бэкенд. Contentful удобен, если команда контент-менеджеров большая и нужен гарантированный аптайм, но за гибкость вы платите 5000+ €/мес. Payload в 2 раза быстрее Strapi при загрузке списков благодаря оптимизации N+1 запросов и tree-shaking. Payload is a headless CMS and application framework that is designed to be developer-friendly and flexible.

Когда Payload имеет смысл

Продукт подходит, когда нужен полный контроль над схемой данных, кастомная аутентификация, или CMS нужно встроить в уже существующий backend. Payload не требует отдельного хостинга — он поднимается там же, где живёт API.

Не стоит использовать, если команда контент-менеджеров большая и привыкла к облачным CMS с гарантированным аптаймом — тогда Contentful или Prismic проще.

Как настроить коллекцию и глобалы?

Типичная структура проекта: src/payload.config.ts — главный конфиг, src/collections/ — типы контента (например, Posts, Users, Media), src/globals/ — singleton-документы (например, SiteSettings). Шаги:

1. Создайте файл коллекции (например, Posts.ts) и определите поля с типами и access.
2. Импортируйте коллекцию в payload.config.ts.
3. Настройте адаптер БД и редактор.
4. Для глобалов создайте аналогичный файл в src/globals/ и добавьте в конфиг.

Пример коллекции постов с Access Control и версионированием:

// 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

Глобальный конфиг включает адаптеры для БД и редактора:

// 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!,
  }),
  // либо PostgreSQL:
  // db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URI } }),
  upload: {
    limits: {
      fileSize: 10_000_000,
    },
  },
  localization: {
    locales: ['ru', 'en'],
    defaultLocale: 'ru',
    fallback: true,
  },
})

Payload поддерживает MongoDB и PostgreSQL. Для PostgreSQL миграции генерируются автоматически: npx payload migrate:create && npx payload migrate.

Как интегрировать Payload с Next.js 14?

Начиная с версии 2.x Payload поддерживает монтирование в Next.js App Router. Весь код умещается в двух файлах:

// 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)

Это означает один next start, один процесс, один деплой.

Хуки, эндпоинты и медиа

Хуки на коллекциях позволяют реагировать на изменения данных. Например, авто-генерация 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}`) }, ], }, 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' }) }, }, ], // медиа-коллекция с генерацией изображений 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' }], } 

Для S3 — официальный плагин @payloadcms/plugin-cloud-storage с адаптером под S3, GCS или Azure.

Сравнение хранилищ: локальное vs S3

Этапы работы и сроки

Что входит в работу

• Разработка схемы коллекций и глобалов под ваш контент
• Настройка Access Control и Roles
• Интеграция с Next.js или Nuxt (App Router)
• Конфигурация медиа и бэкапов
• Развёртывание на сервере (Docker, Nginx)
• Документация API (Postman/Swagger)
• Обучение редакторов работе с админкой
• Гарантия 30 дней на баги

Сроки и стоимость

Базовая интеграция (3–4 коллекции, локализация, Next.js) занимает 5–7 дней. Если нужна кастомная аутентификация, RBAC, сложные хуки — от 2 недель. Стоимость рассчитывается индивидуально, но экономия на лицензиях и инфраструктуре может достигать 50% по сравнению с облачными CMS. Time-to-market сокращается на 30%, а количество запросов к БД уменьшается в 2 раза за счёт правильной настройки depth.

Типичные ошибки и как их избежать

• N+1 запросы при использовании depth > 2 — отключайте populate, когда не нужно
• Отсутствие индексов для slug и дат — добавляйте index: true в поля
• Смешивание сред — храните .env отдельно для разработки и продакшена
• Неправильные MIME-типы — явно задавайте mimeTypes в медиа-коллекции

Мы — команда с 7+ лет опыта в Node.js и 50+ проектах с headless CMS. Закажите интеграцию Payload CMS под ключ. Мы настроим всё необходимое за 5–7 дней. Свяжитесь с нами для оценки проекта.