Puck

Register your Puck collectionsCopy Anchor Link

Tell the plugin which collections hold Puck data, so it can find placements, guard saves during tests, record content changes and make winners permanent.

createExperimentsPlugin({
  // ...
  puck: {
    enabled: true,
    collections: ['pages', { slug: 'templates', field: 'content' }],
  },
})

A slug string uses the collection's puckData field; { slug, field } names another field. The TypeScript type requires enabled. With enabled: false, Puck registration adds no collection hooks: no save guards, content-change tracking or click-goal publish checks. Collections also registered under pages or blocks still receive those integrations' hooks.

Setting enabled: false leaves the collection list in place: placement scans and Make permanent still visit registered collections.

Add the render integrationCopy Anchor Link

In your render config, pass experimentsPuck() to payload-puck's extendConfig:

import { extendConfig } from '@delmaredigital/payload-puck/config'
import { experimentsPuck } from '@delmaredigital/payload-experiments/puck'
import { baseConfig } from './baseConfig'

export const renderConfig = extendConfig({
  base: baseConfig,
  integrations: [experimentsPuck()],
})

Add the editor integrationCopy Anchor Link

In a 'use client' module, create the editor integration once at module scope and pass it to PuckConfigProvider. Creating a new object on every render rebuilds Puck's config and plugin list.

'use client'

import { PuckConfigProvider } from '@delmaredigital/payload-puck/client'
import { experimentsPuckEditor } from '@delmaredigital/payload-experiments/puck/editor'
import { editorConfig } from './editorConfig'

const integrations = [experimentsPuckEditor()]

export function PuckProvider({ children }: { children: React.ReactNode }) {
  return (
    <PuckConfigProvider config={editorConfig} integrations={integrations}>
      {children}
    </PuckConfigProvider>
  )
}

Each integration object contains the Experiment block and its A/B tests sidebar category. The editor object also contains an outline plugin that hides empty version slots the block's test doesn't use; content in an unused slot stays visible with a warning.

Both helpers accept { routes } for non-default Payload admin and API routes. The editor helper also accepts accent; pass the same value as the plugin's theme.accent, since the editor cannot read the Payload config.

experimentsPuck({ routes: { admin: '/cms', api: '/cms-api' } })
experimentsPuckEditor({ routes: { admin: '/cms', api: '/cms-api' }, accent: '#1f3a68' })

Load the editor stylesheet in the iframeCopy Anchor Link

Puck's canvas is an iframe, so the block's editor styles must be in the iframe stylesheet. Import them after Tailwind (if you use it) in the CSS that builds that stylesheet, and list the stylesheet's URL in payload-puck's editorStylesheets:

@import "tailwindcss";
@import "@delmaredigital/payload-experiments/puck/editor.css";

Alternatively, serve the package's puck/editor.css from a public URL and append that URL to editorStylesheets after your own stylesheet. The editor CSS has its own light and dark palette, chosen by data-theme="dark" or the dark class on the iframe's <html>.

Resolve before renderingCopy Anchor Link

On the site, resolve the Puck data for the visitor, render the result, and record exposures for what was rendered:

import { after } from 'next/server'
import { Render, type Data } from '@puckeditor/core'
import { getAssignments, resolveExperimentData, recordExposures } from '@delmaredigital/payload-experiments/rsc'
import { serverRuntime } from '@/experiments/serverRuntime'
import { renderConfig } from '@/puck/renderConfig'

export async function TestedPage({ puckData }: { puckData: Data }) {
  const assignments = await getAssignments(serverRuntime)
  const { data, rendered } = resolveExperimentData(puckData, assignments)
  after(() => recordExposures(serverRuntime, rendered, assignments))
  return <Render config={renderConfig} data={data} />
}

resolveExperimentData removes the versions this visitor should not see and returns only the block tests actually present with the render policy in rendered. Render inside <Suspense> and outside 'use cache'.

For viewport tests, add a client provider; see Client counting.