Розробка кастомних колекцій Payload CMS під ключ

Розробка кастомних колекцій Payload CMS

Уявіть: вам потрібно організувати каталог товарів з варіантами (розмір, колір, залишки), SEO-блоком і правами доступу для різних ролей. Звичайні CMS не дають такої гнучкості — доводиться писати кастомні плагіни або мігрувати на headless. Payload CMS вирішує це завдання на рівні архітектури: колекції, хуки та access control дозволяють побудувати будь-яку бізнес-логіку без компромісів. Ми налаштуємо колекцію так, щоб вона ідеально відповідала вашим процесам. Розберемо на практичному прикладі, як ми будуємо каталог товарів для інтернет-магазину. Економія часу на розробку API — до 50% порівняно з самописними рішеннями.

Як ми будуємо колекцію продуктів

Почнемо з конфігурації. Кожна колекція — це TypeScript-об'єкт з полями, налаштуваннями доступу та хуками. Ось мінімальна структура:

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

const Products: CollectionConfig = {
  slug: 'products',
  labels: {
    singular: 'Товар',
    plural: 'Товары',
  },
  admin: {
    useAsTitle: 'name',
    defaultColumns: ['name', 'price', 'category', 'inStock'],
    group: 'Каталог',
  },
  // ...
}

Потім ми детально опрацьовуємо поля. Payload у 2 рази гнучкіший у налаштуванні полів порівняно з Strapi: підтримує блоки, масиви та групи. Нижче — реальний набір полів для товару з варіантами та SEO-блоком:

fields: [
  // Текстовые поля
  { name: 'name', type: 'text', required: true },
  { name: 'description', type: 'textarea' },
  { name: 'content', type: 'richText' },

  // Цена и дата публикации
  { name: 'price', type: 'number', min: 0, required: true },
  { name: 'publishedAt', type: 'date' },

  // Статус товара
  {
    name: 'status',
    type: 'select',
    options: [
      { label: 'Активен', value: 'active' },
      { label: 'Архив', value: 'archived' },
    ],
    defaultValue: 'active',
  },

  // Изображение
  { name: 'image', type: 'upload', relationTo: 'media' },

  // Связи с категориями и тегами
  {
    name: 'category',
    type: 'relationship',
    relationTo: 'categories',
    hasMany: false,
  },
  {
    name: 'tags',
    type: 'relationship',
    relationTo: 'tags',
    hasMany: true,
  },

  // Массив вариантов (SKU, цвет, размер, остаток)
  {
    name: 'variants',
    type: 'array',
    fields: [
      { name: 'sku', type: 'text', required: true },
      { name: 'color', type: 'text' },
      { name: 'size', type: 'text' },
      { name: 'stock', type: 'number', defaultValue: 0 },
    ],
  },

  // Блоки для динамических секций (например, описание, характеристики, CTA)
  {
    name: 'sections',
    type: 'blocks',
    blocks: [TextBlock, ImageBlock, CTABlock],
  },

  // Группа для SEO-метаданных
  {
    name: 'seo',
    type: 'group',
    fields: [
      { name: 'title', type: 'text' },
      { name: 'description', type: 'textarea' },
    ],
  },
]

Чому потрібні хуки beforeChange та afterChange?

Без хуків колекція — просто CRUD. Хуки додають бізнес-логіку. Ми використовуємо beforeChange для генерації slug на основі назви товару та автоматичного встановлення автора. afterChange — для інвалідації кешу Next.js або надсилання сповіщень у Telegram. Ось як виглядає типовий набір хуків у нашому проєкті:

hooks: {
  beforeChange: [
    async ({ data, req, operation }) => {
      if (operation === 'create' && !data.slug) {
        data.slug = data.name
          .toLowerCase()
          .replace(/\s+/g, '-')
          .replace(/[^\w-]/g, '')
      }
      if (operation === 'create' && req.user) {
        data.author = req.user.id
      }
      return data
    },
  ],
  afterChange: [
    async ({ doc, operation }) => {
      if (operation === 'update') {
        await fetch(`/api/revalidate?path=/products/${doc.slug}`, {
          method: 'POST',
        })
      }
    },
  ],
  afterDelete: [
    async ({ doc }) => {
      console.log(`Product ${doc.id} deleted`)
    },
  ],
}

Як налаштувати доступ до колекції?

Access control у Payload гнучкий: можна задавати правила для читання, створення, оновлення та видалення. Ми часто стикаємося з запитами: «читання — всім, створення — авторизованим, оновлення — лише автору або адміну». Реалізується це через фільтри-умови. Приклад:

access: {
  read: () => true,
  create: ({ req: { user } }) => Boolean(user),
  update: ({ req: { user }, id }) => {
    if (!user) return false
    if (user.role === 'admin') return true
    return { author: { equals: user.id } }
  },
  delete: ({ req: { user } }) => user?.role === 'admin',
},

Що робити з кастомною валідацією?

Іноді стандартні типи полів не покривають вимоги. Наприклад, потрібно перевірити унікальність SKU серед усіх варіантів товару. Для цього використовуємо validate у полі array. Код перевірки виконується на сервері до збереження, що гарантує цілісність даних. Приклад:

{
  name: 'variants',
  type: 'array',
  fields: [
    {
      name: 'sku',
      type: 'text',
      required: true,
      unique: true,
    },
  ],
  validate: (value) => {
    const skus = value.map(v => v.sku)
    if (new Set(skus).size !== skus.length) return 'SKU must be unique'
    return true
  },
}

Версіювання та отримання даних через API

Для контентних проєктів ми вмикаємо версіювання. Payload зберігає до 20 версій з автозбереженням кожні 2 секунди. Це незамінно, коли над контентом працюють кілька редакторів. Після налаштування колекції автоматично з'являються REST і GraphQL ендпоїнти. Ось приклад запиту на серверній стороні (Next.js Server Component) з фільтрацією:

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

const payload = await getPayload({ config })

const result = await payload.find({
  collection: 'products',
  where: {
    and: [
      {
        status: { equals: 'active' },
      },
      {
        category: { equals: categoryId },
      },
      {
        price: { less_than: 10000 },
      },
    ],
  },
  sort: '-createdAt',
  limit: 20,
  page: 1,
  depth: 2,
})

const { docs, totalDocs, hasNextPage } = result

Порівняння типів полів

Порівняння Payload з іншими headless CMS

Це дозволяє заощадити до 40% бюджету порівняно з аналогічними рішеннями на Strapi.

Що входить у розробку та терміни

Ми проектуємо схему полів і зв'язків з урахуванням майбутніх розширень, пишемо хуки та налаштовуємо access control. Налаштування однієї колекції займає 2–4 години. Повний каталог із 5–10 взаємопов'язаних колекцій — 2–4 дні. Вартість розробки однієї колекції можна порівняти з кількома днями роботи розробника, що значно дешевше створення аналогічного функціоналу на самописному рішенні. Включено інтеграцію з існуючою базою даних, документацію по API та навчання команди. Отримайте консультацію для оцінки вашого проєкту.

Замовте розробку кастомних колекцій Payload CMS — отримайте готовий API за 2–4 дні. Наші інженери працюють з Payload з моменту виходу версії 1.0 та сертифіковані з Next.js і TypeScript. За роки роботи ми реалізували понад 50 проєктів на Payload. Гарантуємо, що колекції відповідатимуть вашим вимогам і легко масштабуватимуться.

Джерело: офіційна документація Payload CMS