mcpField
P
puck

puck

github.com/puckeditor开发6284 次安装14 周前更新
代码仓库

关于 puck

Puck 是用于将 React 可视化编辑器 Puck 集成到应用中的技能，指导开发者依据文档配置组件、持久化内容并在浏览器中验证。内容数据由应用自行保存和管理。

主要功能

  1. 01配置应用组件供编辑
  2. 02设置编辑器和渲染路由
  3. 03指导应用自行持久化内容
  4. 04依据文档提供集成指导
  5. 05排查浏览器渲染问题

适用场景

  1. 01将 Puck 集成到现有 React 应用
  2. 02选择组件及可编辑字段
  3. 03诊断样式或 hydration 问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/puckeditor/skills --skill puck

安装后在 Claude Code 中输入/puck确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
ai.md
config-authoring.md
frameworks.md
integration.md
skill-feedback.md
troubleshooting.md

详细介绍

Puck

Puck 是一个 React 可视化编辑器。config 声明应用中的哪些组件可编辑；编辑器会生成 JSON Data 负载；应用存储该负载，并通过 <Render> 将其渲染出来。数据归应用所有——没有托管内容存储。

核心原则

  1. 先看文档。 切勿凭记忆编写 Puck 代码——获取相关页面（见下文的文档）。API 一直在变化，字段或属性名称写错造成的代价远高于获取文档。包的作用域在 0.21 中发生了变化（@measured/puck → @puckeditor/core）；在提供任何与版本相关的建议前，先运行 npm ls @puckeditor/core。
  2. 公开应用的真实组件。 集成的价值在于配置。应用已有组件时，不要另造通用的 Hero/Text/Button 区块。
  3. 不要为了适配 Puck 而改造应用。 在组件的 render 中进行适配，而不是编辑应用的组件。
  4. 编辑前确认范围。 哪些组件可编辑、要添加哪些路由，以及 Data 存储在哪里，都由用户决定；做错这些决定的代价也最高。
  5. 在浏览器中验证，而不是只做类型检查。 集成可以通过编译，却把所有组件都渲染成无样式的状态；这通常是首次运行的结果，并不代表成功。

文档

每个文档页面都可以通过在 URL 末尾添加 .md 获取 Markdown 版本——请获取这些版本，而不是 HTML：

https://puckeditor.com/docs/getting-started.md
https://puckeditor.com/docs/api-reference/fields/slot.md

https://puckeditor.com/llms.txt 是完整的页面索引——不确定哪个页面涵盖相关内容时，先获取它，再获取对应页面的 .md。

注意：当前 .md 转换会从代码块中移除 import 行，因此获取的示例展示了用法，却不包含所需的导入语句。除非页面另有说明，所有内容都从 @puckeditor/core 导入。

最简集成

整个 API 表面只需三个文件。类型、字段和属性见组件配置和 <Puck> 参考。

// puck.config.tsx — maps the app's components to editable Puck components
import type { Config } from "@puckeditor/core";
import { Hero } from "@/components/Hero";

type Props = { Hero: { title: string } };

export const config: Config<Props> = {
  components: {
    Hero: {
      fields: { title: { type: "text" } },
      defaultProps: { title: "Hello, world" },
      render: ({ title }) => <Hero title={title} />,
    },
  },
};

// The editor — client-only. Import "@puckeditor/core/puck.css" from the server parent.
"use client";
import { Puck } from "@puckeditor/core";
import { config } from "@/puck.config";

export function Editor({ data }: { data: any }) {
  // onPublish receives the Data payload — persist it wherever the app stores content
  return <Puck config={config} data={data} onPublish={save} />;
}

// The page — server-safe
import { Render } from "@puckeditor/core";
import { config } from "@/puck.config";

export default function Page({ data }: { data: any }) {
  return <Render config={config} data={data} />;
}

启动新应用

npx create-puck-app my-app 会根据配方搭建应用：next、next-ai、react-router 或 react-router-ai。根据用户使用的框架进行选择；只有用户想要使用 Puck AI 时才选择 -ai 变体（references/ai.md）。

进行任何更改前，先阅读生成的 README——这些配方有意采用了一些简化方案，真实应用必须替换：未经身份验证的 /edit 路由，以及写入本地文件系统而非数据库的持久化方案。两者都必须在部署前修复。此后，references/integration.md 中的配置、持久化和身份验证指南均可照常使用。

特定用例参考

  • 将 Puck 端到端集成到现有应用：references/integration.md
  • 选择要公开的现有组件并设计其字段：references/config-authoring.md
  • 为特定框架或路由器接入编辑器和渲染路由：references/frameworks.md
  • 诊断损坏的集成——无样式预览、FOUC、RSC 错误、水合、拖放：references/troubleshooting.md
  • 添加 Puck AI（由聊天驱动的页面生成插件）：references/ai.md
  • 提交有关此技能的反馈：references/skill-feedback.md

阅读前值得了解的事实

  • <Puck> 仅限客户端使用。<Render> 和 resolveAllData 是仅有的兼容 RSC 的 API。
  • <Puck> 挂载后，data 便无法更改。请在渲染前加载它。
  • Puck 会在 iframe 中渲染画布，并将宿主样式表同步到其中。大多数“Puck 出故障”的报告，实际原因都是应用的样式未能应用到该 iframe 中 — references/troubleshooting.md。
  • 嵌套拖放区域请使用 slot 字段。旧版 DropZone 组件存在 RSC 问题。
  • 编辑器路由和保存端点都可以写入内容。正式发布前，必须为它们接入应用的身份验证。

评论

支持 Markdown