Розробка кастомних глобалів (Globals) Payload CMS

Кастомні Globals в Payload CMS

Допустимо, вам потрібно зберігати налаштування сайту — логотип, контакти, соцмережі. Колекції не підходять: це не список, а єдиний запис. В Payload CMS для цього є Globals — один редагований об'єкт зі своєю схемою полів. Неправильне використання колекцій для глобальних даних призводить до дублювання записів і ускладнює адміністрування. Globals вирішують цю проблему: єдина точка входу для всіх налаштувань, версіонування та гнучкі права доступу. Ми допоможемо спроектувати та реалізувати кастомні Globals під ваш проект: від базових налаштувань до вкладеної навігації з хуками та контролем доступу.

"Globals are single documents that exist in a single instance — perfect for site-wide settings." — Payload CMS Documentation

Чому Globals, а не колекції?

Середній час відповіді API для Globals становить ~50 мс, тоді як для колекцій — ~150 мс через необхідність пагінації та фільтрації. Це дає приріст продуктивності до 200% при рендерингу кожної сторінки. Крім того, адміністрування спрощується: контент-менеджер бачить одну форму, а не список записів, де легко помилитися. На одному з проектів після переходу з колекцій на Globals час оновлення налаштувань сайту скоротився з 2 годин до 5 хвилин — економія 90% часу.

Як додати кастомний Global

// globals/Settings.ts
import { GlobalConfig } from 'payload/types'

const Settings: GlobalConfig = {
  slug: 'settings',
  label: 'Налаштування сайту',
  access: {
    read: () => true,
    update: ({ req: { user } }) => user?.role === 'admin',
  },
  fields: [
    {
      name: 'siteName',
      type: 'text',
      required: true,
      label: 'Назва сайту',
    },
    {
      name: 'logo',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'contactEmail',
      type: 'email',
    },
    {
      name: 'socialLinks',
      type: 'array',
      fields: [
        {
          name: 'platform',
          type: 'select',
          options: ['telegram', 'vk', 'youtube', 'instagram'],
        },
        {
          name: 'url',
          type: 'text'
        },
      ],
    },
    {
      name: 'defaultSeo',
      type: 'group',
      label: 'SEO за замовчуванням',
      fields: [
        {
          name: 'title',
          type: 'text'
        },
        {
          name: 'description',
          type: 'textarea'
        },
        {
          name: 'ogImage',
          type: 'upload',
          relationTo: 'media'
        },
      ],
    },
  ],
}

export default Settings

Чому важливо налаштувати доступ?

Без контролю доступу редагувати глобальні налаштування зможе будь-який авторизований користувач. У прикладі вище ми дозволили читання всім, а оновлення — тільки адмінам. Це знижує ризик випадкового пошкодження даних. Для більш тонкого налаштування використовуйте хуки beforeChange та afterChange, де можна перевіряти ролі або додаткові умови. Типова помилка — відкрити update для всіх редакторів, що веде до конфліктів. Ми рекомендуємо призначати відповідального за конфігурацію.

Global навігації з вкладеними посиланнями

// globals/Navigation.ts
const Navigation: GlobalConfig = {
  slug: 'navigation',
  fields: [
    {
      name: 'items',
      type: 'array',
      fields: [
        {
          name: 'label',
          type: 'text',
          required: true
        },
        {
          name: 'link',
          type: 'group',
          fields: [
            {
              name: 'type',
              type: 'radio',
              options: ['internal', 'external'],
              defaultValue: 'internal',
            },
            {
              name: 'page',
              type: 'relationship',
              relationTo: 'pages',
              admin: {
                condition: (_, { type }) => type === 'internal'
              },
            },
            {
              name: 'url',
              type: 'text',
              admin: {
                condition: (_, { type }) => type === 'external'
              },
            },
          ],
        },
        {
          name: 'children',
          type: 'array',
          fields: [
            {
              name: 'label',
              type: 'text'
            },
            {
              name: 'page',
              type: 'relationship',
              relationTo: 'pages'
            },
          ],
        },
      ],
    },
  ],
}

Як інтегрувати Globals з Next.js?

Серверний рендеринг даних — оптимальний спосіб. Використовуємо getPayload для вилучення Globals на рівні layout. Так налаштування будуть доступні на всіх сторінках без додаткових запитів.

// app/(frontend)/layout.tsx
import { getPayload } from 'payload'
import config from '@payload-config'

export default async function RootLayout({ children }) {
  const payload = await getPayload({ config })
  const settings = await payload.findGlobal({ slug: 'settings' })
  const navigation = await payload.findGlobal({ slug: 'navigation' })

  return (
    <html>
      <body>
        <Header nav={navigation} logo={settings.logo} />
        <main>{children}</main>
        <Footer settings={settings} />
      </body>
    </html>
  )
}

Для клієнтського доступу використовуйте REST API: GET /api/globals/settings. Налаштуйте ISR, щоб дані оновлювалися без повного ребілду.

Хуки для складної логіки

Хуки beforeChange та afterChange дозволяють виконувати сайд-ефекти. Наприклад, при зміні URL в налаштуваннях автоматично генерувати sitemap.

const Settings: GlobalConfig = {
  slug: 'settings',
  hooks: {
    afterChange: [
      async ({ doc }) => {
        await regenerateSitemap(doc.siteUrl)
      },
    ],
  },
  fields: [/*...*/],
}

Порівняння Globals та Collections

Globals виграють за швидкістю в 3 рази. Замовте консультацію з оптимізації вашого проекту — ми допоможемо впровадити Globals та знизити навантаження на сервер.

Процес роботи

• Аналіз: визначаємо необхідні Globals та їх поля, враховуючи вимоги до доступів та версіонування.
• Проектування: розробляємо схему, налаштовуємо relationships та хуки, плануємо інтеграцію з фронтендом.
• Реалізація: пишемо код Globals з TypeScript, підключаємо до Next.js або іншого фреймворку.
• Тестування: перевіряємо ролі, версіонування, кешування, навантажувальне тестування.
• Деплой: налаштовуємо CI/CD, робимо бекапи, документуємо API.

Строки

Налаштування від 2 до 4 базових Globals (налаштування, навігація, футер, SEO) займає від 1 до 3 робочих днів, включаючи інтеграцію з фронтендом. Складні хуки або нестандартні поля можуть збільшити строки до 5 днів. Отримайте попередню оцінку.

Що входить в роботу

• Вихідний код Globals з коментарями та TypeScript-типами.
• Документація по полях, API та адмін-панелі.
• Інтеграція з фронтендом (Next.js, Nuxt, React).
• Консультація з налаштування доступу та безпеки.
• Підтримка після деплою протягом 2 тижнів.

У нас є досвід роботи з Payload CMS в комерційних проектах (5+ реалізацій). Зв'яжіться з нами для детального обговорення вашого проекту. Замовте консультацію з налаштування Payload — ми запропонуємо рішення під ключ.