Разработка плагинов для 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%. Если вы хотите получить готовое решение с гарантией качества, закажите разработку плагина — свяжитесь с нами для обсуждения задачи.