Editor architecture

The plugin has one editor component, PuckEditor, used for every editing case.

• It takes a config prop directly, or reads it from PuckConfigProvider context.
• It has built-in page-tree support through the hasPageTree prop.
• It loads Puck with a dynamic import internally, to prevent hydration mismatches.
• It handles save and publish, unsaved-changes tracking and viewport switching (Mobile, Tablet, Desktop and Full Width previews).
• It shows a drag handle in the component action bar for moving blocks in nested layouts. Pass dnd={{ enableDragHandle: false }} to hide it; other dnd options are passed through to Puck.

PuckEditor is exported from @delmaredigital/payload-puck/client and @delmaredigital/payload-puck/editor. Its props are listed in the editor props reference.

Inside the Payload adminCopy Anchor Link

In the Payload admin the plugin registers a server component, PuckEditorView, at /admin/puck-editor/:collection/:id. It:

• Reads the page as the signed-in user, so the collection's read access applies.
• Detects page-tree by looking for the pageSegment field on the collection, and passes hasPageTree={true} when it finds it.
• Passes the plugin's editorStylesheets, layouts, preview URL and AI settings to PuckEditor.
• Takes the Puck config from PuckConfigProvider context.

The editor fills the viewport rather than rendering inside Payload's nav and header. The canvas iframe gets exactly your editorStylesheets and editorCss, not the admin page's CSS.

PluginsCopy Anchor Link

Puck plugins run in this order: the bundled heading analyzer, plugins from the plugins prop, plugins from PuckConfigProvider, then integration plugins. Pass plugins={false} to disable all of them.