Prismic CMS Integration

Prismic CMS Integration for Content Management

Prismic — a headless CMS with a visual slice builder. Editors build pages from reusable blocks, developers receive typed content via REST or GraphQL API. Suitable for marketing websites, landing pages, and blogs where content changes frequently and deploying just to fix text is not desirable.

What the Integration Includes

Standard work covers: setting up a Prismic repository, designing Custom Types and slices, integrating the SDK into an existing project, configuring Preview and webhooks for rebuild.

Designing the Content Model

Types in Prismic are divided into Single (one record — homepage, settings) and Repeatable (collection — articles, cases).

Slices are reusable sections. One hero slice can be attached to multiple types. The entire model is versioned in 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" }
      }
    }}
  }
}

This JSON is committed to the repository and deployed via Prismic CLI — no manual UI clicks.

SDK Installation and Setup

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

slicemachine/init creates slicemachine.config.json and basic folder structure. For Next.js 14+ the config looks like this:

// 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 Requests

Prismic provides both REST and GraphQL. For most tasks, REST via SDK is more convenient:

// 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 }))
}

For GraphQL — when you need to fetch related documents in a single request:

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

Preview and Draft

The editor wants to see changes before publishing. Prismic supports Draft through 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 })
}

In the Prismic Dashboard, set the Preview URL: https://site.com/api/preview. After clicking "Preview", the editor lands on the site with cookies — Next.js renders the draft.

Webhook and ISR

When Prismic publishes, it calls a webhook. For Next.js, this clears the cache:

// 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')
}

All Prismic requests are tagged as prismic through fetch options — cache invalidation is targeted, not a full rebuild.

Slice Machine and Local Development

Slice Machine — local UI for creating slices. Runs alongside the dev server:

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

Each slice is a folder with index.tsx, model.json, and Stories for Storybook. The model syncs to Prismic with one command:

npx prismic-ts-codegen  # generates TypeScript types from models

After that, all slice fields are typed — typos in field names are caught at build time.

Typical Challenges

Related documents — Prismic doesn't auto-join. If an article has an author field (Link), you must explicitly allow it:

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

Or use graphQuery for more complex structures.

Localization — each language is a separate document. When requesting, pass lang:

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

Content migration order — if the model already exists in another CMS, use Prismic Migration API for programmatic document creation, not manual data entry.

Timeline

Basic integration (up to 5 content types, without custom slices): 3–5 days. With content model design, data migration, and Preview setup: 1–2 weeks depending on scope.