企业官网建设流程全解析

create-puck-app 使用指南：快速生成 Puck 可视化编辑器项目

【免费下载链接】puckThe visual editor for React.项目地址: https://gitcode.com/GitHub_Trending/puc/puck

create-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 目录作为脚手架模板：

二、快速开始：一条命令生成项目

根据 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 采用"命令行参数 + 交互提问"相结合的方式收集信息：

1. 应用名：若未在命令行传入app-name，会通过 inquirer 以 input 方式询问 "What is the name of your app?"；
2. recipe 选择：以 list 方式列出可选 recipe，默认值为next，目前内置Next.js与React Router两个选项；
3. Puck AI 询问：除非显式传入--ai参数，否则会以 confirm 方式询问是否添加 Puck AI（beta）能力，并提示需要 Puck Cloud 账户。

收集完成后，CLI 依次执行以下流程（源码位于 index.js）：

1. 合法性校验：应用名不能为空；目标目录若已存在同名目录会直接报错退出；
2. 计算 recipe 名称：recipe + (是否启用 AI ? "-ai" : "")，从而命中next、next-ai、react-router或react-router-ai模板；
3. 复制模板：遍历模板目录下所有文件（含 dot 文件），逐个写入新建的项目目录；
4. 自动安装依赖：在项目目录内执行yarn install或对应包管理器的i命令，输出透传终端；
5. 自动 Git 初始化：若新目录不在既有 Git 仓库中，则执行git init、git add .并提交build(puck): generate app初始提交；
6. 输出启动指引，若启用了 Puck AI，还会额外打印云端接入配置链接提示。

四、CLI 选项详解

虽然 README 只展示了最简用法，但 index.js 的 commander 定义还提供了四个常用选项：

如果未显式指定包管理器，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 完成：

1. 遍历recipes/下全部文件（含 dot 文件）；
2. 若对应模板位置已存在同名.hbs文件，则该文件跳过复制——说明它由 Handlebars 模板接管，需要维护者手工同步模板内容；
3. 其余文件直接复制到templates/；
4. 特殊处理.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