create-puck-app 使用指南快速生成 Puck 可视化编辑器项目【免费下载链接】puckThe visual editor for React.项目地址: https://gitcode.com/GitHub_Trending/puc/puckcreate-puck-app是 Puck 官方提供的脚手架 CLI用于一键生成基于 Puck 可视化编辑器The visual editor for React的完整可运行项目。本指南将围绕该工具的命令用法、交互流程、CLI 选项、底层实现与模板机制展开帮助你在几分钟内基于 Next.js 或 React Router 搭建起带编辑器的应用并理解其内部工作原理以便按需定制。一、认识 create-puck-app一个基于 recipes 的脚手架create-puck-app的核心职责是生成 recipes。所谓 recipe是指 Puck 官方维护的一组配方式示例项目——每个 recipe 都预先配置好了 Puck 编辑器、页面渲染、数据库读写示例用 JSON 文件模拟、路由与静态生成等完整链路拿到手即可直接运行。该工具定位为一个独立可发布的 npm 包位于 packages/create-puck-app当前版本为 0.23.0通过bin字段暴露create-puck-app命令。它本身是一段由 index.js 实现的 Node CLI 脚本依赖commander命令行解析、inquirer交互式提问、glob模板文件遍历、handlebars模板编译和prettier等库。当前仓库内置了四种 recipe均可在 recipes 目录下找到源码同时也被同步到 templates 目录作为脚手架模板recipe技术栈特点nextNext.js App Router使用静态页面生成适合内容型站点react-routerReact Router v7使用动态路由可在任意层级创建页面next-aiNext.js Puck AI额外集成puckeditor/plugin-ai与puckeditor/cloud-clientreact-router-aiReact Router Puck AI额外集成 Puck AI需 Puck Cloud 账户二、快速开始一条命令生成项目根据 create-puck-app/README.md使用任意主流包管理器均可启动脚手架# 使用 npm npx create-puck-app my-app# 使用 yarn yarn create puck-app my-app提示npx/yarn create会自动临时安装最新版create-puck-app并执行无需事先全局安装。命令中的my-app是目标应用目录名如果省略CLI 会在后续交互中询问。执行完毕后工具会输出下一步提示Done! Now run: cd my-app npm run dev进入目录并启动开发服务器即可打开 Puck 编辑器开始可视化创作。三、交互式流程从提问到出项目从 index.js 的源码可以看到CLI 采用命令行参数 交互提问相结合的方式收集信息应用名若未在命令行传入app-name会通过 inquirer 以 input 方式询问 What is the name of your app?recipe 选择以 list 方式列出可选 recipe默认值为next目前内置Next.js与React Router两个选项Puck AI 询问除非显式传入--ai参数否则会以 confirm 方式询问是否添加 Puck AIbeta能力并提示需要 Puck Cloud 账户。收集完成后CLI 依次执行以下流程源码位于 index.js合法性校验应用名不能为空目标目录若已存在同名目录会直接报错退出计算 recipe 名称recipe (是否启用 AI ? -ai : )从而命中next、next-ai、react-router或react-router-ai模板复制模板遍历模板目录下所有文件含 dot 文件逐个写入新建的项目目录自动安装依赖在项目目录内执行yarn install或对应包管理器的i命令输出透传终端自动 Git 初始化若新目录不在既有 Git 仓库中则执行git init、git add .并提交build(puck): generate app初始提交输出启动指引若启用了 Puck AI还会额外打印云端接入配置链接提示。四、CLI 选项详解虽然 README 只展示了最简用法但 index.js 的 commander 定义还提供了四个常用选项选项作用--use-npm显式指定使用 npm 引导并安装依赖--use-yarn显式指定使用 Yarn--use-pnpm显式指定使用 pnpm--ai直接启用 Puck AI 集成跳过 AI 相关的交互提问如果未显式指定包管理器CLI 会通过 getPkgManager() 解析环境变量npm_config_user_agent自动探测当前正在使用的包管理器优先级为 yarn → pnpm → npm做到用什么启动就用什么装依赖与 create-next-app 的实现思路一致。实际用法示例# 显式使用 pnpm 并启用 Puck AI npx create-puck-app my-app --use-pnpm --ai # 非交互式使用指定应用名 显式选择包管理器 npx create-puck-app my-app --use-npm注意--ai与 AI 交互提问只是脚手架层面的选择开关Puck AI 的实际鉴权与云服务对接需要 Puck Cloud 账户集成后的配置入口见生成的next-ai/react-router-ai项目说明。五、生成的项目长什么样recipe 模板解析以nextrecipe 为例其完整源码位于 recipes/next包含编辑路由app/puck/[...puckPath] 下的编辑器页面与客户端组件以及 app/puck/api 下的数据持久化 API 路由预览路由app/[...puckPath]下负责渲染已发布页面配合 lib/get-page.ts 读取数据Puck 配置puck.config.tsx 定义组件与字段数据文件database.json 模拟数据库存储页面数据代理配置proxy.ts 等辅助文件。react-routerrecipe见 recipes/react-router则采用 React Router v7 的动态路由体系app/routes下的puck-splat.tsx处理任意层级路径、app/routes.ts注册路由配合 app/lib/pages.server.ts 在服务端按路径查找页面数据实现在任意层级创建页面。生成到用户目录时模板中的占位内容会被 Handlebar 渲染为真实值。例如 next/package.json.hbs{ name: {{appName}}, version: 1.0.0, private: true, scripts: { dev: next dev, build: next build, start: next start }, dependencies: { puckeditor/core: {{puckVersion}}, classnames: ^2.3.2, next: ^16.0.8, react: ^19.2.1, react-dom: ^19.2.1 } }其中{{appName}}替换为用户输入的应用名{{puckVersion}}则被替换为^ create-puck-app 自身版本号见 index.js保证生成项目的 Puck 依赖版本与脚手架版本严格对齐。而 react-router/tsconfig.json.hbs 则展示了路径别名~/*→./app/*、moduleResolution: bundler等针对 Vite React Router 的 TypeScript 配置react-router的 package.json.hbs 还声明了node 20.0.0的 engines 要求。启用 AI 的模板next-ai/package.json.hbs则在next基础上额外引入puckeditor/plugin-ai与puckeditor/cloud-client两个依赖。六、深入原理模板目录与源码如何同步仓库中存在两套内容高度一致的目录recipes/面向用户阅读的示例源码与packages/create-puck-app/templates/脚手架实际使用的模板。二者的同步由 scripts/generate.js 完成遍历recipes/下全部文件含 dot 文件若对应模板位置已存在同名.hbs文件则该文件跳过复制——说明它由 Handlebars 模板接管需要维护者手工同步模板内容其余文件直接复制到templates/特殊处理.gitignore复制为gitignore去掉点前缀避免 npm 发布时因.gitignore被忽略而导致模板丢失见 package.json 中的removeGitignore/restoreGitignore脚本与 generate.js 的注释说明。该同步在发布前通过prepublishOnly钩子自动执行即yarn generate保证发布到 npm 的脚手架模板始终与仓库内 recipe 保持一致。而在脚手架运行阶段index.js 会把模板中的.hbs文件用 Handlebars 编译并替换变量后写入目标目录非.hbs文件原样拷贝同时把gitignore改回.gitignore、移除.hbs后缀。七、上手建议与注意事项首选官方 recipe需求与next或react-router匹配时直接用npx create-puck-app my-app起步省去编辑器接入、路由、数据持久化的一整套繁琐配置想加 Puck AI在交互提问中选择启用或在命令行直接追加--ai生成后按 CLI 输出提示到 Puck Cloud 完成鉴权接入想改默认行为阅读 packages/create-puck-app/index.js 的 commander 定义即可自行扩展选项若需新增 recipe可参考 recipes 下现有目录结构编写再通过yarn generate见 scripts/generate.js同步到 templates注意工程前提react-router系 recipe 要求 Node.js 20且新项目会自动初始化 Git 并生成一次初始提交若目录名已存在脚手架会直接报错请更换名称或先清理目录。总体而言create-puck-app以极小的学习成本把 Puck 编辑器从库升级为开箱即用的完整应用——一条命令即可获得可编辑、可发布、可运行的参考实现是上手 Puck 或搭建内部内容管理平台的最快路径。【免费下载链接】puckThe visual editor for React.项目地址: https://gitcode.com/GitHub_Trending/puc/puck创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考