Інтеграція CMS Prismic для управління контентом

Інтеграція CMS Prismic для управління контентом

Prismic — headless CMS з візуальним конструктором слайсів. Редактори збирають сторінки з переиспользуємих блоків, розробники отримують типизований контент через REST або GraphQL API. Підходить для маркетингових сайтів, лендингів та блогів, де контент змінюється часто, а деплоїти ради правки тексту не хочеться.

Що входить в інтеграцію

Стандартна робота покриває: настройку репозиторію Prismic, проектування Custom Types та слайсів, інтеграцію SDK у наявний проект, настройку Preview та webhook-ів для ребілду.

Проектування моделі контенту

Типи в Prismic поділяються на Single (одна запис — головна сторінка, настройки) та Repeatable (колекція — статті, кейси).

Слайси — це переиспользуємі секції. Один слайс hero можна підключити до кількох типів. Вся модель версіонується в JSON:

{
  "Main": {
    "uid": { "type": "UID", "config": { "label": "URL slug" } },
    "title": { "type": "StructuredText", "config": { "single": "heading1" } },
    "body": { "type": "Slices", "fieldset": "Slice Zone", "config": {
      "choices": {
        "hero": { "type": "SharedSlice" },
        "text_block": { "type": "SharedSlice" },
        "image_gallery": { "type": "SharedSlice" }
      }
    }}
  }
}

Цей JSON коммітиться в репозиторій та деплоїться через Prismic CLI — жодних ручних кліків в UI.

Установка та настройка SDK

npm install @prismicio/client @prismicio/react @prismicio/next
npx @slicemachine/init

slicemachine/init створює slicemachine.config.json та базову структуру папок. Для Next.js 14+ конфіг виглядає так:

// prismicio.ts
import * as prismic from '@prismicio/client'
import { CreateClientConfig, enableAutoPreviews } from '@prismicio/next'

export const repositoryName = process.env.PRISMIC_REPOSITORY_NAME!

export function createClient(config: CreateClientConfig = {}) {
  const client = prismic.createClient(repositoryName, {
    accessToken: process.env.PRISMIC_ACCESS_TOKEN,
    routes: [
      { type: 'page', path: '/:uid' },
      { type: 'blog_post', path: '/blog/:uid' },
    ],
    ...config,
  })
  enableAutoPreviews({ client, previewData: config.previewData, req: config.req })
  return client
}

Запити до API

Prismic надає як REST, так і GraphQL. Для більшості задач REST через SDK зручніше:

// app/[uid]/page.tsx
import { createClient } from '@/prismicio'
import { notFound } from 'next/navigation'

export default async function Page({ params }: { params: { uid: string } }) {
  const client = createClient()

  const page = await client
    .getByUID('page', params.uid)
    .catch(() => notFound())

  return <SliceZone slices={page.data.body} components={components} />
}

export async function generateStaticParams() {
  const client = createClient()
  const pages = await client.getAllByType('page')
  return pages.map(p => ({ uid: p.uid }))
}

Для GraphQL — коли потрібно підтягнути пов'язані документи в одному запиті:

{
  allBlog_posts(sortBy: publish_date_DESC, first: 10) {
    edges {
      node {
        _meta { uid }
        title
        cover_image
        author {
          ... on Author {
            name
            avatar
          }
        }
      }
    }
  }
}

Preview та Draft

Редактор хоче бачити зміни до публікації. Prismic підтримує Draft через Preview:

// app/api/preview/route.ts
import { redirectToPreviewURL } from '@prismicio/next'
import { createClient } from '@/prismicio'

export async function GET(request: Request) {
  const client = createClient()
  return redirectToPreviewURL({ client, request })
}

В Prismic Dashboard вказуємо Preview URL: https://site.com/api/preview. Після натиснення «Preview» редактор потрапляє на сайт з кук — Next.js рендерить чорновик.

Webhook та ISR

При публікації Prismic дергає webhook. Для Next.js це скидання кешу:

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'

export async function POST(request: Request) {
  const secret = request.headers.get('x-prismic-secret')
  if (secret !== process.env.PRISMIC_WEBHOOK_SECRET) {
    return new Response('Unauthorized', { status: 401 })
  }
  revalidateTag('prismic')
  return new Response('Revalidated')
}

Все запити до Prismic помічаються тегом prismic через fetch options — скидання кешу точкове, не повний ребілд.

Slice Machine та локальна розробка

Slice Machine — локальний UI для створення слайсів. Запускається поруч з dev-сервером:

npm run slicemachine  # port 9999
npm run dev           # port 3000

Кожен слайс — це папка з index.tsx, model.json та Stories для Storybook. Модель синхронізується в Prismic однією командою:

npx prismic-ts-codegen  # генерирує TypeScript типи з моделей

Після цього всі поля слайсів типізовані — опечатка в назві поля поймається на етапі збірки.

Типічні складності

Пов'язані документи — Prismic не робить join автоматично. Якщо в статті є поле author (Link), його потрібно явно дозволити:

const post = await client.getByUID('blog_post', uid, {
  fetchLinks: ['author.name', 'author.avatar'],
})

Або використовувати graphQuery для складніших структур.

Локалізація — кожна мова це окремий документ. При запиті потрібно передавати lang:

const page = await client.getByUID('page', uid, { lang: 'uk' })

Порядок міграції контенту — якщо модель вже є в іншій CMS, використовуємо Prismic Migration API для програмного створення документів, а не ручний ввід.

Терміни

Базова інтеграція (до 5 типів контенту, без кастомних слайсів): 3–5 днів. З проектуванням моделі контенту, міграцією даних та настройкою Preview: 1–2 тижні залежно від обсягу.