@delmaredigital/payload-puck

v0.6.4

Published

3 hours ago

Puck visual page builder plugin for Payload CMS

0High
0Medium
0Low

allandelmare

payload payloadcms payload-plugin puck page-builder visual-editor cms

@delmaredigital/payload-puck

A PayloadCMS plugin for integrating Puck visual page builder. Build pages visually with drag-and-drop components while leveraging Payload's content management capabilities.

Installation

Requirements

| Dependency | Version | Purpose | |------------|---------|---------| | @puckeditor/core | >= 0.21.0 | Visual editor core | | payload | >= 3.69.0 | CMS backend | | @payloadcms/next | >= 3.69.0 | Payload Next.js integration | | next | >= 15.4.8 | React framework | | react | >= 19.2.1 | UI library | | @tailwindcss/typography | >= 0.5.0 | RichText component styling |

Note: Puck 0.21+ moved from @measured/puck to @puckeditor/core. This plugin requires the new package scope.

Install

pnpm add @delmaredigital/payload-puck @puckeditor/core

Quick Start

The plugin integrates directly into Payload's admin UI with minimal configuration. API endpoints and admin views are registered automatically.

Step 1: Add the Plugin

// src/payload.config.ts
import { buildConfig } from 'payload'
import { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'

export default buildConfig({
  plugins: [
    createPuckPlugin({
      pagesCollection: 'pages', // Collection slug (default: 'pages')
    }),
  ],
  // ...
})

This automatically:

Creates a pages collection with Puck fields (or adds fields to your existing collection)
Registers API endpoints at /api/puck/:collection
Adds the Puck editor view at /admin/puck-editor/:collection/:id
Adds "Edit with Puck" buttons to the admin UI

Step 2: Provide Puck Configuration

Wrap your app with PuckConfigProvider to supply the Puck configuration. This makes the config available to the editor via React context.

// app/(app)/layout.tsx (covers both admin and frontend)
import { PuckConfigProvider } from '@delmaredigital/payload-puck/client'
import { editorConfig } from '@delmaredigital/payload-puck/config/editor'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PuckConfigProvider config={editorConfig}>
          {children}
        </PuckConfigProvider>
      </body>
    </html>
  )
}

Tip: PuckConfigProvider also accepts layouts and theme props. See Layouts and Theming sections.

Note: For custom editor UIs (outside Payload admin), you can also pass the config directly to PuckEditor instead of using the context provider.

Alternative: Payload Admin Provider (vanilla starter pattern)

If you're using the vanilla Payload starter structure, you can register the provider via the admin config instead:

// src/payload.config.ts
export default buildConfig({
  admin: {
    components: {
      providers: ['@/components/admin/PuckProvider'],
    },
  },
  // ...
})

// src/components/admin/PuckProvider.tsx
'use client'

import { PuckConfigProvider } from '@delmaredigital/payload-puck/client'
import { editorConfig } from '@delmaredigital/payload-puck/config/editor'

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

Step 3: Create a Frontend Route

The plugin can't auto-create frontend routes (Next.js App Router is file-based), but here's copy-paste ready code:

import { getPayload } from 'payload'
import config from '@payload-config'
import { PageRenderer } from '@delmaredigital/payload-puck/render'
import { baseConfig } from '@delmaredigital/payload-puck/config'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'

// Fetch page by slug (or homepage if no slug)
// Only returns published pages - unpublished pages will 404
async function getPage(slug?: string[]) {
  const payload = await getPayload({ config })
  const slugPath = slug?.join('/') || ''

  // Try to find by slug, or find homepage
  // Filter for published pages only (_status: 'published')
  const { docs } = await payload.find({
    collection: 'pages',
    where: {
      and: [
        { _status: { equals: 'published' } },
        slugPath
          ? { slug: { equals: slugPath } }
          : { isHomepage: { equals: true } },
      ],
    },
    limit: 1,
  })

  return docs[0] || null
}

// Generate metadata from page SEO fields
export async function generateMetadata({
  params
}: {
  params: Promise<{ slug?: string[] }>
}): Promise<Metadata> {
  const { slug } = await params
  const page = await getPage(slug)

  if (!page) return {}

  return {
    title: page.meta?.title || page.title,
    description: page.meta?.description,
  }
}

// Render the page
export default async function Page({
  params
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const page = await getPage(slug)

  if (!page) notFound()

  return <PageRenderer config={baseConfig} data={page.puckData} />
}

Note: The [[...slug]] pattern with double brackets makes the slug optional, so this handles both / (homepage) and /any/path.

That's It!

The plugin registers the editor view at /admin/puck-editor/:collection/:id
"Edit with Puck" buttons appear in the collection list view
The editor runs inside Payload's admin UI with full navigation
API endpoints are handled automatically via Payload's endpoint system

Adding to Existing Projects

⚠️ Important: If you're adding Puck to a project with existing frontend routes, you must update those routes to render Puck content.

When adding Puck to an existing Payload project:

✅ Add the plugin to payload.config.ts
✅ Add PuckConfigProvider to your admin layout
⚠️ Update your frontend page templates to render puckData

Without step 3, Puck pages will render blank because your existing routes only look for legacy block fields like layout or hero.

Option A: Hybrid Rendering (recommended for migration)

Use HybridPageRenderer to support both legacy blocks and Puck pages:

import { HybridPageRenderer } from '@delmaredigital/payload-puck/render'
import { baseConfig } from '@delmaredigital/payload-puck/config'
import { LegacyBlockRenderer } from '@/components/LegacyBlockRenderer'

export default async function Page({ params }) {
  const page = await getPage(params.slug)

  return (
    <HybridPageRenderer
      page={page}
      config={baseConfig}
      legacyRenderer={(blocks) => <LegacyBlockRenderer blocks={blocks} />}
    />
  )
}

Option B: Manual Detection

Add conditional logic to check editorVersion:

// Check if page was created with Puck
const isPuckPage = page.editorVersion === 'puck' && page.puckData?.content?.length > 0

if (isPuckPage) {
  return <PageRenderer config={baseConfig} data={page.puckData} />
}

// Fall back to legacy rendering
return <LegacyBlockRenderer blocks={page.layout} />

Option C: Custom Components

If you have custom Puck components (not just the built-in ones), create a client wrapper:

// components/PuckPageRenderer.tsx
'use client'

import { Render } from '@puckeditor/core'
import { myCustomConfig } from '@/puck/config'

export function PuckPageRenderer({ data }) {
  return <Render config={myCustomConfig} data={data} />
}

Then use this wrapper in your page template instead of PageRenderer.

Styling Setup

Tailwind Typography (Required)

Required only if using the RichText component.

The RichText component uses @tailwindcss/typography:

pnpm add @tailwindcss/typography

Tailwind v4:

@import "tailwindcss";
@plugin "@tailwindcss/typography";

Tailwind v3:

// tailwind.config.js
module.exports = {
  plugins: [require('@tailwindcss/typography')],
}

Package Scanning (Required)

Required if your project uses Tailwind CSS. Ensures component classes are included in your build.

Tell Tailwind to scan the plugin's components:

Tailwind v4:

/* Adjust path relative to your CSS file */
@source "../node_modules/@delmaredigital/payload-puck";

Tailwind v3:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@delmaredigital/payload-puck/**/*.{js,mjs,jsx,tsx}',
  ],
}

Theme CSS Variables (Optional)

Optional - the plugin includes sensible defaults. Define these only to customize colors in rendered content (links, borders, etc).

The plugin uses shadcn/ui-style CSS variables. If you don't use shadcn/ui and want to customize colors, define these in your CSS:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
}

Core Concepts

Server vs Client Configuration

The plugin provides two configurations for React Server Components:

| Config | Import | Use Case | |--------|--------|----------| | baseConfig | @delmaredigital/payload-puck/config | Server-safe rendering with PageRenderer | | editorConfig | @delmaredigital/payload-puck/config/editor | Client-side editing with full interactivity |

// Server component - use baseConfig
import { baseConfig } from '@delmaredigital/payload-puck/config'
<PageRenderer config={baseConfig} data={page.puckData} />

// PuckConfigProvider - use editorConfig
import { editorConfig } from '@delmaredigital/payload-puck/config/editor'
<PuckConfigProvider config={editorConfig}>

Draft System

The editor uses Payload's native draft system. The plugin automatically enables drafts on the pages collection. You can also enable it manually:

{
  slug: 'pages',
  versions: {
    drafts: true,
  },
}

The editor header provides:

Save - Saves as draft without publishing
Publish - Publishes the page (sets _status: 'published')
Unpublish - Reverts a published page to draft status (appears only when published)

Components

Layout

| Component | Description | |-----------|-------------| | Container | Content wrapper with max-width and background | | Flex | Flexible box layout with direction and alignment | | Grid | CSS Grid layout with responsive columns | | Section | Two-layer: full-bleed section + constrained content area | | Spacer | Vertical/horizontal spacing element | | Template | Save/load reusable component arrangements |

Typography

| Component | Description | |-----------|-------------| | Heading | H1-H6 headings with size and alignment | | Text | Paragraph text with styling options | | RichText | Puck's native richtext editor with enhancements: font sizes, text colors with opacity, highlights, superscript/subscript, and inline editing on canvas |

Media & Interactive

| Component | Description | |-----------|-------------| | Image | Responsive image with alt text | | Button | Styled button/link with variants | | Card | Content card with optional image | | Divider | Horizontal rule with styles | | Accordion | Expandable content sections (first item opens by default) |

Semantic HTML Elements

Layout components (Section, Flex, Container, Grid) support semantic HTML output for better SEO and accessibility:

| Component | Available Elements | |-----------|-------------------| | Section | section, article, aside, nav, header, footer, main, div | | Flex | div, nav, ul, ol, aside, section | | Container | div, article, aside, section | | Grid | div, ul, ol |

Select the appropriate HTML element in the component's sidebar to output semantic markup.

Responsive Controls

Layout components support per-breakpoint customization:

Dimensions - Width, max-width, height constraints
Padding/Margin - Spacing per breakpoint
Visibility - Show/hide at specific breakpoints
Viewport Preview - Mobile, Tablet, Desktop, and Full Width options

Custom Fields

All fields are imported from @delmaredigital/payload-puck/fields.

Field Reference

| Field | Description | |-------|-------------| | MediaField | Payload media library integration | | RichTextField | Puck's native richtext with enhancements (colors, font sizes, highlights) | | ColorPickerField | Color picker with opacity and presets | | BackgroundField | Solid colors, gradients, images | | PaddingField / MarginField | Visual spacing editors | | BorderField | Border width, style, color, radius | | DimensionsField | Width/height with constraints | | AlignmentField | Text alignment (left, center, right) | | ContentAlignmentField | Visual 3x3 grid selector for positioning (d-pad style) | | SizeField | Preset sizes (sm, default, lg) with custom mode | | AnimationField | Entrance animations | | ResponsiveVisibilityField | Show/hide per breakpoint | | FolderPickerField | Hierarchical folder selection (page-tree) | | PageSegmentField | URL segment with slugification (page-tree) | | SlugPreviewField | Read-only computed slug (page-tree) |

Usage Example

import { createMediaField, createBackgroundField, backgroundValueToCSS } from '@delmaredigital/payload-puck/fields'

const HeroConfig = {
  fields: {
    image: createMediaField({ label: 'Background Image' }),
    background: createBackgroundField({ label: 'Overlay' }),
  },
  render: ({ image, background }) => (
    <section style={{ background: backgroundValueToCSS(background) }}>
      {/* content */}
    </section>
  ),
}

CSS Helper Functions

import {
  backgroundValueToCSS,
  dimensionsValueToCSS,
  animationValueToCSS,
  visibilityValueToCSS,
  alignmentToFlexCSS,
  alignmentToGridCSS,
  sizeValueToCSS,
  getSizeClasses,
} from '@delmaredigital/payload-puck/fields'

ContentAlignmentField Example

The ContentAlignmentField provides a visual 3x3 grid selector for content positioning:

import {
  createContentAlignmentField,
  alignmentToFlexCSS,
  alignmentToGridCSS,
} from '@delmaredigital/payload-puck/fields'

const BannerConfig = {
  fields: {
    contentPosition: createContentAlignmentField({ label: 'Content Position' }),
  },
  render: ({ contentPosition }) => (
    <div style={{
      display: 'flex',
      minHeight: '400px',
      ...alignmentToFlexCSS(contentPosition), // Converts to justify-content + align-items
    }}>
      <div>Positioned content</div>
    </div>
  ),
}

Helper functions:

alignmentToFlexCSS() - For Flexbox containers (justify-content + align-items)
alignmentToGridCSS() - For Grid containers (justify-content + align-content)
alignmentToPlaceSelfCSS() - For individual grid items (place-self)
alignmentToTailwind() - Returns Tailwind classes (justify-* items-*)

Building Custom Components

The plugin exports individual component configs and field factories for building custom Puck configurations.

Cherry-Picking Components

Import only the components you need:

import {
  SectionConfig,
  HeadingConfig,
  TextConfig,
  ImageConfig,
  ButtonConfig,
} from '@delmaredigital/payload-puck/components'

export const puckConfig: Config = {
  components: {
    Section: SectionConfig,
    Heading: HeadingConfig,
    Text: TextConfig,
    Image: ImageConfig,
    Button: ButtonConfig,
  },
  categories: {
    layout: { components: ['Section'] },
    content: { components: ['Heading', 'Text', 'Image', 'Button'] },
  },
}

Using Field Factories

Build custom components with pre-built fields:

import type { ComponentConfig } from '@puckeditor/core'
import {
  createMediaField,
  createBackgroundField,
  createPaddingField,
  backgroundValueToCSS,
  paddingValueToCSS,
} from '@delmaredigital/payload-puck/fields'

export const HeroConfig: ComponentConfig = {
  label: 'Hero',
  fields: {
    image: createMediaField({ label: 'Background Image' }),
    overlay: createBackgroundField({ label: 'Overlay' }),
    padding: createPaddingField({ label: 'Padding' }),
  },
  defaultProps: {
    image: null,
    overlay: null,
    padding: { top: 80, bottom: 80, left: 24, right: 24, unit: 'px', linked: false },
  },
  render: ({ image, overlay, padding }) => (
    <section
      style={{
        background: backgroundValueToCSS(overlay),
        padding: paddingValueToCSS(padding),
      }}
    >
      {/* Hero content */}
    </section>
  ),
}

Server vs Editor Variants

For PageRenderer (frontend), components need server-safe configs without React hooks:

// Import server variants for PageRenderer
import {
  SectionServerConfig,
  HeadingServerConfig,
  TextServerConfig,
} from '@delmaredigital/payload-puck/components'

<PageRenderer config={{ components: { Section: SectionServerConfig, ... } }} data={page.puckData} />

For custom components, create two files:

MyComponent.tsx - Full editor version with fields and interactivity
MyComponent.server.tsx - Server-safe version (no hooks, no 'use client')

Extending Built-in Configs

Use extendConfig() to add custom components:

import { extendConfig, fullConfig } from '@delmaredigital/payload-puck/config/editor'
import { HeroConfig } from './components/Hero'

export const puckConfig = extendConfig({
  base: fullConfig,
  components: {
    Hero: HeroConfig,
  },
  categories: {
    custom: { title: 'Custom', components: ['Hero'] },
  },
})

Note: Use fullConfig from /config/editor for extending the editor. For server-side rendering, use baseConfig from /config.

Using Custom Config with Provider

After creating your custom config, pass it to PuckConfigProvider:

// components/admin/PuckProvider.tsx
'use client'
import { PuckConfigProvider } from '@delmaredigital/payload-puck/client'
import { puckConfig } from '@/puck/config.editor'
import { siteLayouts } from '@/lib/puck-layouts'

export default function PuckProvider({ children }: { children: React.ReactNode }) {
  return (
    <PuckConfigProvider config={puckConfig} layouts={siteLayouts}>
      {children}
    </PuckConfigProvider>
  )
}

For Payload admin, register the provider in your Payload config:

// payload.config.ts
export default buildConfig({
  admin: {
    components: {
      providers: ['@/components/admin/PuckProvider'],
    },
  },
  // ...
})

This is the recommended pattern for Payload apps. The provider wraps only the admin UI, keeping your frontend layout separate.

Available Field Factories

| Factory | Description | |---------|-------------| | createMediaField() | Payload media library picker | | createBackgroundField() | Solid, gradient, or image backgrounds | | createColorPickerField() | Color picker with opacity | | createPaddingField() | Visual padding editor | | createMarginField() | Visual margin editor | | createBorderField() | Border styling | | createDimensionsField() | Width/height constraints | | createAnimationField() | Entrance animations | | createAlignmentField() | Text alignment (left, center, right) | | createContentAlignmentField() | Visual 3x3 grid positioning selector | | createSizeField() | Size presets with custom mode | | createRichTextField() | Puck's native richtext with colors, font sizes, highlights | | createResponsiveVisibilityField() | Show/hide per breakpoint |

CSS Helper Functions

Convert field values to CSS:

import {
  backgroundValueToCSS,
  paddingValueToCSS,
  marginValueToCSS,
  borderValueToCSS,
  dimensionsValueToCSS,
  colorValueToCSS,
  alignmentToFlexCSS,
  alignmentToGridCSS,
  sizeValueToCSS,
} from '@delmaredigital/payload-puck/fields'

const style = {
  background: backgroundValueToCSS(props.background),
  padding: paddingValueToCSS(props.padding),
  ...dimensionsValueToCSS(props.dimensions),
  ...alignmentToFlexCSS(props.contentAlignment),
  ...sizeValueToCSS(props.size),
}

Theming

Customize button styles, color presets, and focus rings:

import { PageRenderer } from '@delmaredigital/payload-puck/render'
import { ThemeProvider } from '@delmaredigital/payload-puck/theme'

<ThemeProvider theme={{
  buttonVariants: {
    default: { classes: 'bg-primary text-white hover:bg-primary/90' },
    secondary: { classes: 'bg-secondary text-foreground hover:bg-secondary/90' },
  },
  focusRingColor: 'focus:ring-primary',
  colorPresets: [
    { hex: '#3b82f6', label: 'Brand Blue' },
    { hex: '#10b981', label: 'Success' },
  ],
}}>
  <PageRenderer config={baseConfig} data={page.puckData} />
</ThemeProvider>

Access theme values in custom components with useTheme():

import { useTheme } from '@delmaredigital/payload-puck/theme'

function CustomButton({ variant }) {
  const theme = useTheme()
  const classes = theme.buttonVariants[variant]?.classes
  return <button className={classes}>...</button>
}

Layouts

Define page layouts with headers, footers, and styling:

// lib/puck-layouts.ts
import type { LayoutDefinition } from '@delmaredigital/payload-puck/layouts'
import { SiteHeader } from '@/components/header'
import { SiteFooter } from '@/components/footer'

export const siteLayouts: LayoutDefinition[] = [
  {
    value: 'default',
    label: 'Default',
    description: 'Standard page with header and footer',
    maxWidth: '1200px',
    header: SiteHeader,
    footer: SiteFooter,
    stickyHeaderHeight: 80,
  },
  {
    value: 'landing',
    label: 'Landing',
    description: 'Full-width landing page',
    fullWidth: true,
  },
]

Pass layouts to the PuckConfigProvider:

<PuckConfigProvider config={editorConfig} layouts={siteLayouts}>
  {children}
</PuckConfigProvider>

And use them with PageRenderer:

import { LayoutWrapper } from '@delmaredigital/payload-puck/layouts'

const layout = siteLayouts.find(l => l.value === page.puckData?.root?.props?.pageLayout)

<LayoutWrapper layout={layout}>
  <PageRenderer config={baseConfig} data={page.puckData} />
</LayoutWrapper>

Avoiding Double Headers/Footers

When your host app already provides a global header/footer via its root layout (e.g., Next.js layout.tsx), use createRenderLayouts() to strip them from Puck layouts:

import { HybridPageRenderer, createRenderLayouts } from '@delmaredigital/payload-puck/render'
import { siteLayouts } from '@/lib/puck-layouts' // layouts with header/footer for editor

// Strip header/footer for rendering (host app layout provides them)
const renderLayouts = createRenderLayouts(siteLayouts)

export function PageRenderer({ page }) {
  const layout = renderLayouts.find(l => l.value === page.puckData?.root?.props?.pageLayout)

  return (
    <LayoutWrapper layout={layout}>
      <HybridPageRenderer page={page} config={baseConfig} />
    </LayoutWrapper>
  )
}

This pattern keeps header/footer in your editor layouts for realistic preview, but avoids double headers when rendering.

Dark Mode Support

The Puck editor automatically detects PayloadCMS dark mode and applies CSS overrides to ensure visibility. It also provides a preview toggle to test how pages look in both light and dark modes.

How It Works

Editor UI: Automatically detects dark mode via .dark class (PayloadCMS) or prefers-color-scheme (OS preference), then injects Puck CSS variable overrides
Preview Iframe: A sun/moon toggle lets you switch the preview content between light and dark modes independently from the editor UI

Configuration

Dark mode is enabled by default. You can customize via props on PuckEditor:

<PuckEditor
  autoDetectDarkMode={true}           // Auto-detect PayloadCMS dark mode (default: true)
  showPreviewDarkModeToggle={true}    // Show light/dark toggle in header (default: true)
  initialPreviewDarkMode={false}      // Start preview in light mode (default: false)
/>

Using Components Directly

For custom editor implementations:

import {
  DarkModeStyles,
  PreviewModeToggle,
  useDarkMode,
} from '@delmaredigital/payload-puck/editor'

function CustomEditor() {
  const { isDarkMode, source } = useDarkMode()
  const [previewDark, setPreviewDark] = useState(false)

  return (
    <>
      {/* Inject dark mode CSS overrides when detected */}
      <DarkModeStyles />

      {/* Toggle for preview iframe */}
      <PreviewModeToggle
        isDarkMode={previewDark}
        onToggle={setPreviewDark}
      />

      <Puck ... />
    </>
  )
}

Page-Tree Integration

When @delmaredigital/payload-page-tree is detected, the plugin automatically adds folder management to the Puck sidebar.

How It Works

The plugin checks if your collection has a pageSegment field (page-tree's signature). When detected:

Folder Picker - Select a folder from the hierarchy
Page Segment - Edit the page's URL segment
Slug Preview - See the computed slug (folder path + segment)

Plugin Configuration

createPuckPlugin({
  // Auto-detect (default)
  pageTreeIntegration: undefined,

  // Explicitly enable with custom config
  pageTreeIntegration: {
    folderSlug: 'payload-folders',
    pageSegmentFieldName: 'pageSegment',
  },

  // Explicitly disable
  pageTreeIntegration: false,
})

Custom Editor UI

For custom editor implementations outside Payload admin, use the hasPageTree prop:

import { PuckEditor } from '@delmaredigital/payload-puck/client'
import { editorConfig } from '@delmaredigital/payload-puck/config/editor'

<PuckEditor
  config={editorConfig}
  pageId={page.id}
  initialData={page.puckData}
  pageTitle={page.title}
  pageSlug={page.slug}
  apiEndpoint="/api/puck/pages"
  hasPageTree={true}
  folder={page.folder}
  pageSegment={page.pageSegment}
/>

Performance

Detection is instant - it reads the in-memory collection config, no database queries.

Hybrid Integration

Add Puck to existing collections with legacy blocks.

Automatic (Recommended)

If you already have a pages collection, the plugin adds only the Puck-specific fields:

// payload.config.ts
export default buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'layout', type: 'blocks', blocks: [HeroBlock, CTABlock] },
      ],
    },
  ],
  plugins: [
    createPuckPlugin({ pagesCollection: 'pages' }),
  ],
})

The editorVersion field auto-detects whether pages use legacy blocks or Puck.

Manual with `getPuckCollectionConfig()` (Recommended)

When you need the isHomepage field, use getPuckCollectionConfig() which returns both fields AND hooks. This ensures the homepage uniqueness validation is included:

import { getPuckCollectionConfig } from '@delmaredigital/payload-puck'

const { fields: puckFields, hooks: puckHooks } = getPuckCollectionConfig({
  includeSEO: true,
  includeEditorVersion: true,
  includePageLayout: true,
  includeIsHomepage: true, // Includes uniqueness hook automatically
})

export const Pages: CollectionConfig = {
  slug: 'pages',
  hooks: {
    beforeChange: [
      ...(puckHooks.beforeChange ?? []),
      // Your other beforeChange hooks...
    ],
    afterChange: [
      // Your afterChange hooks...
    ],
  },
  fields: [
    { name: 'title', type: 'text' },
    { name: 'layout', type: 'blocks', blocks: [...] },
    ...puckFields,
  ],
}

Manual with `getPuckFields()` (Fields Only)

If you don't need isHomepage or want to configure hooks manually:

import { getPuckFields, createIsHomepageUniqueHook } from '@delmaredigital/payload-puck'

export const Pages: CollectionConfig = {
  slug: 'pages',
  hooks: {
    // Required if using includeIsHomepage: true
    beforeChange: [createIsHomepageUniqueHook()],
  },
  fields: [
    { name: 'title', type: 'text' },
    { name: 'layout', type: 'blocks', blocks: [...] },
    ...getPuckFields({
      includeSEO: true,
      includeEditorVersion: true,
      includePageLayout: true,
      includeIsHomepage: true, // Note: requires hook above for uniqueness
    }),
  ],
}

Note: The isHomepage field allows marking one page as the homepage. The createIsHomepageUniqueHook() ensures only one page can be marked as homepage at a time, prompting users to swap if a homepage already exists.

Rendering Hybrid Pages

import { HybridPageRenderer } from '@delmaredigital/payload-puck/render'
import { LegacyBlockRenderer } from '@/components/LegacyBlockRenderer'

<HybridPageRenderer
  page={page}
  config={puckConfig}
  legacyRenderer={(blocks) => <LegacyBlockRenderer blocks={blocks} />}
/>

AI Integration

Early Preview: While Puck's AI features are powerful, this plugin's implementation is still in early stages and under active development. Expect changes as we refine the integration.

The plugin integrates with Puck AI to enable AI-assisted page generation. Users can describe what they want in natural language, and the AI builds complete page layouts using your components.

Requirements

PUCK_API_KEY environment variable (from Puck Cloud)
AI features require @puckeditor/plugin-ai and @puckeditor/cloud-client (bundled with the plugin)

Quick Start

Enable AI in your plugin configuration:

createPuckPlugin({
  pagesCollection: 'pages',
  ai: {
    enabled: true,
    context: 'We are Acme Corp, a B2B SaaS company. Use professional language.',
  },
})

This automatically:

Registers the AI chat endpoint at /api/puck/ai
Adds the AI chat plugin to the editor
Applies comprehensive component instructions for better generation quality

Dynamic Business Context

Instead of hardcoding context in your config, you can manage it through Payload admin:

createPuckPlugin({
  ai: {
    enabled: true,
    contextCollection: true,  // Creates puck-ai-context collection
  },
})

This creates a puck-ai-context collection where you can add entries for:

Brand Guidelines - Colors, fonts, brand voice
Tone of Voice - How to communicate
Product Information - What you sell/offer
Industry Context - Your market and audience
Technical Requirements - Specific constraints
Page Patterns - Common layout structures

Context entries can be enabled/disabled and ordered. The AI receives all enabled entries sorted by order.

Context Editor Plugin

When contextCollection: true, a "Context" panel appears in the Puck plugin rail. Users can view, create, edit, and toggle context entries directly in the editor without visiting Payload admin.

Prompt Management

Store reusable prompts in Payload:

createPuckPlugin({
  ai: {
    enabled: true,
    promptsCollection: true,  // Creates puck-ai-prompts collection
    examplePrompts: [
      { label: 'Landing page', prompt: 'Create a landing page for...' },
    ],
  },
})

Prompts from the collection appear in the AI chat interface. A "Prompts" panel in the plugin rail allows in-editor prompt management.

Custom Tools

Enable the AI to query your data:

import { z } from 'zod'

createPuckPlugin({
  ai: {
    enabled: true,
    tools: {
      getProducts: {
        description: 'Get products from the database',
        inputSchema: z.object({ category: z.string() }),
        execute: async ({ category }, { payload }) => {
          return await payload.find({
            collection: 'products',
            where: { category: { equals: category } },
          })
        },
      },
    },
  },
})

Tools receive a context object with the Payload instance and authenticated user.

AI Configuration Options

| Option | Default | Description | |--------|---------|-------------| | enabled | false | Enable AI features | | context | undefined | Static system context for the AI | | contextCollection | false | Create puck-ai-context collection for dynamic context | | promptsCollection | false | Create puck-ai-prompts collection for reusable prompts | | examplePrompts | [] | Static example prompts for the chat interface | | tools | undefined | Custom tools for AI to query your system | | componentInstructions | undefined | Override default component AI instructions |

Component Instructions

The plugin includes comprehensive instructions for all built-in components, teaching the AI:

Correct field names and values
Component composition patterns
Page structure best practices (Hero → Features → CTA flow)
Semantic HTML usage

To customize or extend:

createPuckPlugin({
  ai: {
    enabled: true,
    componentInstructions: {
      Heading: {
        ai: { instructions: 'Use our brand voice: professional but approachable' },
        fields: {
          text: { ai: { instructions: 'Keep under 8 words' } },
        },
      },
    },
  },
})

Standalone API Routes

For custom implementations outside the plugin:

// app/api/puck/[...all]/route.ts
import { createPuckAiApiRoutes } from '@delmaredigital/payload-puck/ai'
import config from '@payload-config'

export const POST = createPuckAiApiRoutes({
  payloadConfig: config,
  auth: {
    authenticate: async (request) => {
      // Your auth implementation
      return { user: { id: '...' } }
    },
  },
  ai: {
    context: 'Your business context...',
  },
})

AI Exports

import {
  // Plugins
  createAiPlugin,
  createPromptEditorPlugin,
  createContextEditorPlugin,

  // Hooks
  useAiPrompts,
  useAiContext,

  // Config utilities
  injectAiConfig,
  comprehensiveComponentAiConfig,
  pagePatternSystemContext,

  // API routes
  createPuckAiApiRoutes,
  createAiGenerate,
} from '@delmaredigital/payload-puck/ai'

Advanced Configuration

Plugin Options

| Option | Default | Description | |--------|---------|-------------| | pagesCollection | 'pages' | Collection slug to use for pages | | autoGenerateCollection | true | Create the collection if it doesn't exist, or add Puck fields to existing | | enableEndpoints | true | Register API endpoints at /api/puck/:collection for the editor | | enableAdminView | true | Register the Puck editor view in Payload admin | | adminViewPath | '/puck-editor' | Path for the editor (full path: /admin/puck-editor/:collection/:id) | | pageTreeIntegration | auto-detect | Integration with @delmaredigital/payload-page-tree | | layouts | undefined | Layout definitions for page templates | | editorStylesheet | undefined | Path to CSS file for editor iframe styling (e.g., 'src/app/globals.css') | | editorStylesheetCompiled | undefined | Path to pre-compiled CSS for production (e.g., '/puck-editor-styles.css') | | editorStylesheetUrls | [] | Additional stylesheet URLs for the editor (e.g., Google Fonts) |

createPuckPlugin({
  pagesCollection: 'pages',
  autoGenerateCollection: true,
  enableEndpoints: true,
  enableAdminView: true,
  adminViewPath: '/puck-editor',
  pageTreeIntegration: undefined, // auto-detects

  // Collection overrides (merged with generated collection)
  collectionOverrides: {
    admin: {
      defaultColumns: ['title', 'slug', 'updatedAt'],
    },
  },

  // Access control
  access: {
    read: () => true,
    create: ({ req }) => !!req.user,
    update: ({ req }) => !!req.user,
    delete: ({ req }) => !!req.user,
  },
})

Editor Stylesheet (Iframe Styling)

The Puck editor renders page content in an iframe. By default, this iframe doesn't have access to your frontend's CSS (Tailwind utilities, CSS variables, fonts). The editorStylesheet option solves this by compiling and serving your CSS.

Development (Runtime Compilation)

In development, CSS is compiled at runtime for hot reload support:

createPuckPlugin({
  pagesCollection: 'pages',
  editorStylesheet: 'src/app/(frontend)/globals.css',
  editorStylesheetUrls: [
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap'
  ],
})

How it works:

You specify your CSS file path in the plugin config
The plugin creates an endpoint at /api/puck/styles
On first request, the CSS is compiled with PostCSS/Tailwind and cached
The iframe loads this compiled CSS

Production (Build-Time Compilation)

Runtime compilation fails on serverless platforms (Vercel, Netlify, etc.) because source CSS files aren't deployed—only compiled .next output is included. Use withPuckCSS() to compile CSS at build time:

Step 1: Wrap your Next.js config

// next.config.js
import { withPuckCSS } from '@delmaredigital/payload-puck/next'
import { withPayload } from '@payloadcms/next/withPayload'

const nextConfig = {
  // your config...
}

export default withPuckCSS({
  cssInput: 'src/app/(frontend)/globals.css',
})(withPayload(nextConfig))

Step 2: Add the compiled path to your plugin config

createPuckPlugin({
  pagesCollection: 'pages',
  editorStylesheet: 'src/app/(frontend)/globals.css',      // For dev (runtime)
  editorStylesheetCompiled: '/puck-editor-styles.css',     // For prod (static)
  editorStylesheetUrls: [
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap'
  ],
})

How it works:

During next build, the wrapper compiles your CSS to public/puck-editor-styles.css
In production (NODE_ENV=production), the plugin serves the static file
In development, runtime compilation continues working for hot reload

withPuckCSS options:

| Option | Default | Description | |--------|---------|-------------| | cssInput | (required) | Path to source CSS file | | cssOutput | 'puck-editor-styles.css' | Output filename in public/ | | skipInDev | true | Skip compilation in development |

Requirements

postcss must be installed in your project
For Tailwind v4: @tailwindcss/postcss
For Tailwind v3: tailwindcss

Custom API Routes (Advanced)

The built-in endpoints handle most use cases. Only disable them if you need custom authentication or middleware.

If needed, three route factories are available:

| Factory | Route Pattern | Methods | |---------|---------------|---------| | createPuckApiRoutes | /api/puck/[collection] | GET (list), POST (create) | | createPuckApiRoutesWithId | /api/puck/[collection]/[id] | GET, PATCH, DELETE | | createPuckApiRoutesVersions | /api/puck/[collection]/[id]/versions | GET, POST (restore) |

See the JSDoc in @delmaredigital/payload-puck/api for usage examples.

Export Reference

| Export Path | Description | |-------------|-------------| | @delmaredigital/payload-puck | Plugin creation, field utilities | | @delmaredigital/payload-puck/plugin | createPuckPlugin | | @delmaredigital/payload-puck/config | baseConfig, createConfig(), extendConfig() | | @delmaredigital/payload-puck/config/editor | editorConfig for editing | | @delmaredigital/payload-puck/client | PuckEditor, PuckConfigProvider, page-tree utilities | | @delmaredigital/payload-puck/editor | PuckEditor, HeaderActions, editor hooks | | @delmaredigital/payload-puck/rsc | PuckEditorView for Payload admin views | | @delmaredigital/payload-puck/render | PageRenderer, HybridPageRenderer | | @delmaredigital/payload-puck/fields | Custom Puck fields and CSS helpers | | @delmaredigital/payload-puck/components | Component configs for custom configurations | | @delmaredigital/payload-puck/theme | ThemeProvider, theme utilities | | @delmaredigital/payload-puck/layouts | Layout definitions, LayoutWrapper | | @delmaredigital/payload-puck/api | API route factories (for custom implementations) | | @delmaredigital/payload-puck/ai | AI plugins, hooks, config utilities, API routes | | @delmaredigital/payload-puck/next | withPuckCSS Next.js config wrapper for build-time CSS | | @delmaredigital/payload-puck/admin/client | EditWithPuckButton, EditWithPuckCell |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@delmaredigital/payload-puck

Table of Contents

Installation

Requirements

Install

Quick Start

Step 1: Add the Plugin

Step 2: Provide Puck Configuration

Step 3: Create a Frontend Route

That's It!

Adding to Existing Projects

Styling Setup

Tailwind Typography (Required)

Package Scanning (Required)

Theme CSS Variables (Optional)

Core Concepts

Server vs Client Configuration

Draft System

Components

Layout

Typography

Media & Interactive

Semantic HTML Elements

Responsive Controls

Custom Fields

Field Reference

Usage Example

CSS Helper Functions

ContentAlignmentField Example

Building Custom Components

Cherry-Picking Components

Using Field Factories

Server vs Editor Variants

Extending Built-in Configs

Using Custom Config with Provider

Available Field Factories

CSS Helper Functions

Theming

Layouts

Avoiding Double Headers/Footers

Dark Mode Support

How It Works

Configuration

Using Components Directly

Page-Tree Integration

How It Works

Plugin Configuration

Custom Editor UI

Performance

Hybrid Integration

Automatic (Recommended)

Manual with getPuckCollectionConfig() (Recommended)

Manual with getPuckFields() (Fields Only)

Rendering Hybrid Pages

AI Integration

Requirements

Quick Start

Dynamic Business Context

Context Editor Plugin

Prompt Management

Custom Tools

AI Configuration Options

Component Instructions

Standalone API Routes

AI Exports

Advanced Configuration

Plugin Options

Editor Stylesheet (Iframe Styling)

Development (Runtime Compilation)

Production (Build-Time Compilation)

Requirements

Custom API Routes (Advanced)

Export Reference

License

Manual with `getPuckCollectionConfig()` (Recommended)

Manual with `getPuckFields()` (Fields Only)