Інтеграція 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 — це headless CMS та фреймворк для додатків, створений для зручності розробників та гнучкості.

Коли Payload має сенс

Продукт підходить, коли потрібен повний контроль над схемою даних, кастомна аутентифікація, або CMS потрібно вбудувати в уже існуючий бекенд. 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 днів. Зв'яжіться з нами для оцінки проекту.