Разработка плагинов для Payload CMS: архитектура и реализация

Разработка плагинов для Payload CMS

Представьте: у вас 10 коллекций, в каждую нужно добавить одинаковые SEO-поля — мета-заголовок, описание, изображение и флаг noIndex. Ручное добавление занимает 2-3 часа, но при изменении структуры поля придется править каждую коллекцию — это 20-30 часов на поддержку в год. Плагины Payload CMS решают эту проблему раз и навсегда: вы описываете поля один раз в коде плагина, а затем подключаете его к нужным коллекциям одной строкой. Мы разрабатываем такие плагины под ключ с гарантией качества и поддержкой. Наш опыт — более 5 лет и 15+ плагинов для разных проектов. Если вам нужен плагин, свяжитесь с нами для консультации.

Почему плагины выгодны?

Основная проблема — дублирование кода. Если функциональность нужна в нескольких коллекциях, копирование полей и хуков раздувает базу кода. Вторая проблема — сложность поддержки: изменение логики требует правки в каждом месте. Третья — отсутствие единого интерфейса для схожих операций. Плагины централизуют функциональность: SEO, аудит, поиск, кастомные эндпоинты. Например, плагин SEO добавляет одинаковые мета-поля во все указанные коллекции, а плагин аудита протоколирует все изменения в единую коллекцию логов. Сравнение с ручным добавлением: плагин в 3-4 раза быстрее в поддержке и менее подвержен ошибкам. Внедрение сокращает время на 30-40%.

Как разработать плагин для Payload CMS?

Согласно официальной документации Payload CMS, плагин — это "функция, которая принимает конфигурацию и возвращает измененную конфигурацию". Это не магия: плагин просто добавляет коллекции, поля, хуки, эндпоинты и компоненты к существующей конфигурации перед инициализацией CMS. Официальные плагины (@payloadcms/seo, @payloadcms/form-builder) следуют этой же модели.

// Тип плагина
type Plugin = (incomingConfig: Config) => Config

// Простейший плагин
const myPlugin: Plugin = (config) => {
  return {
    ...config,
    collections: [
      ...(config.collections || []), // добавить коллекцию
    ],
    hooks: {
      ...config.hooks,
      afterInit: [
        ...(config.hooks?.afterInit || []), // добавить хук
      ],
    },
  }
}

export default buildConfig({
  plugins: [myPlugin],
})

Примеры плагинов: SEO, аудит, поиск

Плагин SEO добавляет мета-поля во все указанные коллекции:

// plugins/seo/index.ts
import type { Config, CollectionConfig, GlobalConfig } from 'payload/types'

interface SEOPluginConfig {
  collections?: string[] // slug коллекций, куда добавить SEO-поля
  globals?: string[]
  uploadsCollection?: string
  generateTitle?: (doc: any) => string
  generateDescription?: (doc: any) => string
}

export const seoPlugin = (pluginConfig: SEOPluginConfig) => (config: Config): Config => {
  const seoFields = [
    {
      name: 'meta',
      type: 'group' as const,
      label: 'SEO',
      admin: {
        position: 'sidebar' as const,
      },
      fields: [
        {
          name: 'title',
          type: 'text' as const,
          admin: {
            description: ({ doc }: any) => pluginConfig.generateTitle?.(doc) || 'Автозаполнение: заголовок документа',
          },
        },
        {
          name: 'description',
          type: 'textarea' as const,
          maxLength: 160,
        },
        {
          name: 'image',
          type: 'upload' as const,
          relationTo: pluginConfig.uploadsCollection || 'media',
        },
        {
          name: 'noIndex',
          type: 'checkbox' as const,
          defaultValue: false,
        },
      ],
    },
  ]

  return {
    ...config,
    collections: config.collections?.map(collection => {
      if (pluginConfig.collections?.includes(collection.slug)) {
        return {
          ...collection,
          fields: [...(collection.fields || []), ...seoFields],
        }
      }
      return collection
    }),
    globals: config.globals?.map(global => {
      if (pluginConfig.globals?.includes(global.slug)) {
        return {
          ...global,
          fields: [...(global.fields || []), ...seoFields],
        }
      }
      return global
    }),
    hooks: {
      ...config.hooks,
      afterRead: [
        ...(config.hooks?.afterRead || []),
        ({ doc }: any) => {
          if (!doc.meta?.title && pluginConfig.generateTitle) {
            doc.meta = {
              ...doc.meta,
              title: pluginConfig.generateTitle(doc),
            }
          }
          return doc
        },
      ],
    },
  }
}

Плагин аудита действий логирует все изменения:

// plugins/audit-log/index.ts
import type { Config } from 'payload/types'

interface AuditLogConfig {
  collections: string[]
}

export const auditLogPlugin = ({ collections }: AuditLogConfig) => (config: Config): Config => {
  const auditCollection = {
    slug: 'audit-logs',
    admin: {
      hidden: true,
    },
    access: {
      read: ({ req }: any) => req.user?.role === 'admin',
      create: () => false,
      update: () => false,
      delete: () => false,
    },
    fields: [
      {
        name: 'collection',
        type: 'text' as const,
      },
      {
        name: 'docId',
        type: 'text' as const,
      },
      {
        name: 'operation',
        type: 'text' as const,
      },
      {
        name: 'user',
        type: 'relationship' as const,
        relationTo: 'users' as const,
      },
      {
        name: 'before',
        type: 'json' as const,
      },
      {
        name: 'after',
        type: 'json' as const,
      },
      {
        name: 'timestamp',
        type: 'date' as const,
      },
    ],
  }

  const auditedCollections = config.collections?.map(collection => {
    if (!collections.includes(collection.slug)) return collection
    return {
      ...collection,
      hooks: {
        ...collection.hooks,
        afterChange: [
          ...(collection.hooks?.afterChange || []),
          async ({ doc, previousDoc, operation, req }: any) => {
            if (!req.payload) return
            await req.payload.create({
              collection: 'audit-logs',
              data: {
                collection: collection.slug,
                docId: String(doc.id),
                operation,
                user: req.user?.id,
                before: previousDoc || null,
                after: doc,
                timestamp: new Date().toISOString(),
              },
              disableVerificationEmail: true,
            })
          },
        ],
      },
    }
  })

  return {
    ...config,
    collections: [
      ...(auditedCollections || []),
      auditCollection,
    ],
  }
}

Поисковый плагин добавляет кастомный эндпоинт /search:

// plugins/search/index.ts
export const searchPlugin = (config: Config): Config => ({
  ...config,
  endpoints: [
    ...(config.endpoints || []),
    {
      path: '/search',
      method: 'get' as const,
      handler: async (req: any, res: any) => {
        const { q } = req.query
        if (!q) return res.json({ docs: [] })
        const results = await Promise.all([
          req.payload.find({
            collection: 'posts',
            where: {
              or: [
                { title: { like: q } },
                { excerpt: { like: q } }
              ]
            },
            limit: 5,
          }),
          req.payload.find({
            collection: 'products',
            where: {
              name: { like: q }
            },
            limit: 5,
          }),
        ])
        return res.json({
          docs: [
            ...results[0].docs.map(d => ({ ...d, _type: 'post' })),
            ...results[1].docs.map(d => ({ ...d, _type: 'product' })),
          ],
        })
      },
    },
  ],
})

Публикация плагина как npm-пакета

// package.json плагина
{
  "name": "@myorg/payload-plugin-seo",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "peerDependencies": {
    "payload": "^2.0.0"
  },
  "scripts": {
    "build": "tsc"
  }
}

Экспорт плагина из src/index.ts: export { seoPlugin } from './plugin'; export type { SEOPluginConfig } from './types';. После сборки публикуйте пакет в npm. Документация в README обязательна.

Сравнение типов плагинов

Типы хуков, используемых в плагинах

Процесс разработки плагина

1. Анализ требований: определяем коллекции, хуки и эндпоинты. Учитываем возможные коллизии с существующими полями.
2. Проектирование интерфейса: создаём TypeScript-типы для конфигурации плагина. Используем строгую типизацию, чтобы избежать ошибок на этапе компиляции.
3. Реализация: пишем код плагина, используем глобальные хуки для централизованных изменений. Код покрываем unit-тестами (Jest) с покрытием не менее 90%.
4. Тестирование: проверяем критичные сценарии, включая граничные случаи (пустые коллекции, отсутствие хуков). Также проводим интеграционное тестирование с реальной Payload CMS.
5. Публикация и документация: готовим README с примерами использования, собираем TypeScript в dist и публикуем в npm. Весь процесс занимает от 3 до 10 дней в зависимости от сложности.

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

• Исходный код плагина на TypeScript с полной типизацией.
• Unit-тесты (Jest) с покрытием не менее 90%.
• Документация (README) с примерами конфигурации и использования.
• Поддержка после внедрения: исправления и доработки в течение месяца.

Типичные ошибки при разработке плагинов

• Не проверять, что коллекции и хуки могут быть undefined или пустыми — вызывают ошибки при запуске.
• Использовать хук afterInit для добавления полей вместо модификации коллекций напрямую — после инициализации поля уже не применить.
• Забывать экспортировать типы конфигурации плагина — пользователи не смогут получить автодополнение в IDE.

Когда заказывают разработку плагина?

Каждый наш плагин тестируется и документируется. Мы находим оптимальные архитектурные решения, учитывая специфику вашего проекта. Плагин окупается уже через несколько месяцев использования — экономия времени на добавлении однотипных полей достигает 40%. Если вы хотите получить готовое решение с гарантией качества, закажите разработку плагина — свяжитесь с нами для обсуждения задачи.