JoshuaShepherd Puck visual editor
Canonical documentation: https://puckeditor.com/docs
Release note: Puck 0.21 adds AI (beta), richtext fields, and the Plugin Rail. Summary: Puck 0.21 blog.
Reference implementation (blocks + editor + site_pages): sibling repo movemental-visual-editor — keep .claude/skills/puck-visual-editor/SKILL.md there in sync with this file for the full repo path table.
1. Mental model
Config—components,fields,defaultProps,render,categories,root,resolveData,permissions, …Data—content,root, legacyzones. Prefer slots over DropZones (migration guide).<Puck />= client editor;<Render />+resolveAllData= RSC-friendly when config is server-safe (Server components).
2. Official documentation index
Getting started
| Topic | URL |
|---|---|
| Introduction | Introduction |
| Install and minimal editor | Getting Started |
Integrating Puck
| Topic | URL |
|---|---|
| Component configuration | Component configuration |
| Root configuration | Root configuration |
| Categories | Categories |
| Multi-column layouts | Multi-column layouts |
| Dynamic props | Dynamic props |
| Dynamic fields | Dynamic fields |
| External data sources | External data sources |
| Server components | Server components |
| Data migration | Data migration |
| Viewports | Viewports |
| Feature toggling / permissions | Feature toggling |
| Rich text editing | Rich text editing |
| Overlay portals | Overlay portals |
Extending Puck
| Topic | URL |
|---|---|
| Composition | Composition |
| Custom fields | Custom fields |
| Field transforms | Field transforms |
| Internal Puck API | Internal Puck API |
| Theming | Theming |
| Plugins (Plugin Rail) | Plugin API |
| UI overrides | UI overrides |
API reference (frequently used)
| Topic | URL |
|---|---|
Config |
Config |
ComponentConfig |
Component config |
Data model |
Data model |
<Puck /> |
Puck |
| Puck subcomponents | Puck components |
<Render /> |
Render |
| Permissions | Permissions |
slot field |
Slot field |
richtext field |
Richtext field |
| RichTextMenu | RichTextMenu |
migrate() |
migrate |
transformProps() |
transformProps |
resolveAllData() |
resolveAllData |
registerOverlayPortal |
registerOverlayPortal |
| Plugins API | Plugins |
Puck AI (cloud beta)
| Topic | URL |
|---|---|
| Overview | AI overview |
| Getting started | AI getting started |
| AI configuration | AI configuration |
| Business context | Business context |
| Tools | AI tools |
| Headless generation | Headless generation |
3. Practices (short)
- Stable
typekeys in JSON; use Data migration when renaming. - Per-page palettes: filter
Config.componentsandcategoriesfrom DB-driven allowlists — not stored insidepuck_dataalone. - Slot
allow/disallowfor nested regions vs global palette (Slot field). import "@puckeditor/core/puck.css".- Rich text: follow Rich text editing; treat public HTML carefully.
4. This monorepo (non-profit-dashboard)
There is no embedded Puck editor package here today. Use this skill when:
- Planning a Supabase-backed page builder that must align with movemental-visual-editor, or
- Authoring prompts and specs (see
_docs/_prompts/09-puck-per-page-components-supabase-setup.md).
Executable checklist and packages/blocks paths: ../movemental-visual-editor/.claude/skills/puck-visual-editor/SKILL.md and _docs/_prompts/08-puck-per-page-components-supabase-setup.md in that repo.
5. Related agent skills
| Skill | Use when |
|---|---|
.claude/skills/migrations-workflow/SKILL.md |
Schema changes for site_pages / puck_data |
.claude/skills/supabase-security-audit/SKILL.md |
RLS on content tables |
.claude/skills/agent-tool/SKILL.md |
Puck AI Tools or custom orchestration |
.claude/skills/agent-create/SKILL.md |
Agents that emit or validate Puck JSON |
.claude/skills/agent-instructions/SKILL.md |
Constraining models to registered component keys |