create-ydesign

画布编辑器项目脚手架 —— 一条命令快速初始化基于 @ydesign/react-editor 的设计 / 图片编辑器项目。交互与参数设计参照 create-vite。

提供多种垂类场景模板（完整设计编辑器 / 最小编辑器 / 图片编辑器），每个场景都计划提供 React 与 Vue 两种框架版本，并区分 JavaScript 和 TypeScript 语言版本。

🚧 目前仅 React 流程已打通；Vue 版本仍在开发中。

快速开始

需要 Node.js 20.19+ / 22.12+。

使用 NPM：

npm create ydesign@latest

使用 Yarn：

yarn create ydesign

使用 PNPM：

pnpm create ydesign

随后按照交互提示输入项目名 → 选择框架 → 选择语言 → 选择模板 → 是否立即安装并启动。整体流程：

✔ 项目名称：       my-editor
✔ 选择一个框架：    React           # Vue 显示「（开发中）」
✔ 选择语言版本：    TypeScript / JavaScript
✔ 选择一个模板：    editor / minimal / photo
✔ 使用 npm 安装依赖并立即启动？  Yes / No

直接指定项目名与模板

也可以通过命令行参数跳过交互：

# npm（注意 npm 需要额外的 -- 透传参数给脚手架）
npm create ydesign@latest my-editor -- --template react-editor-ts

# yarn
yarn create ydesign my-editor --template react-minimal

# pnpm
pnpm create ydesign my-editor --template react-photo-ts

可用模板

模板命名为 <框架>-<场景>[-ts]：JavaScript 版不带后缀，TypeScript 版带 -ts（与 create-vite 一致）。

| 场景 | 说明 | TypeScript | JavaScript | | --------- | ----------------------------------------------------------------- | ------------------ | --------------- | | editor | 完整设计编辑器：顶栏 + 侧边栏 + 工具栏 + 画布 + 多语言 + 主题切换 | react-editor-ts | react-editor | | minimal | 最小可运行编辑器：仅工具栏 + 画布 + 缩放按钮 | react-minimal-ts | react-minimal | | photo | 图片编辑器模式：上传 / 图片 / 蒙版 / 滤镜 | react-photo-ts | react-photo |

🚧 Vue 模板（vue-editor-ts / vue-editor 等）正在开发中，预计随 @ydesign/vue-editor 一起发布。

依赖说明

所有 React 模板（editor / minimal / photo）的 package.json 采用同一套依赖策略，与 @ydesign/react-editor 的包设计一致。

模板里写了什么、没写什么

| 包 | 在 @ydesign/react-editor 中 | 模板 package.json | 原因 | | --- | --- | --- | --- | | react / react-dom | peer | ✅ 显式声明 | peer 依赖需由宿主项目提供 | | mobx / mobx-react-lite / mobx-state-tree / styled-components | peer | ✅ 显式声明 | 同上 | | @ydesign/ui-react / @ydesign/ui-tokens | dependencies（react-editor 传递） | ✅ 显式声明 | 主题系统与业务层 UI（顶栏、弹窗等） | | @ydesign/react-editor | — | ✅ 显式声明 | UI 库本体 | | @ydesign/core | dependencies（传递依赖） | ❌ 不声明 | 安装 UI 库时自动带入 |

为什么 @ydesign/core 不在模板里？

@ydesign/core 是画布渲染核心（基于 fabric.js）。模板业务代码只从 @ydesign/react-editor 导入，不直接 import from '@ydesign/core'。

它在 @ydesign/react-editor 的 dependencies 中声明，执行 npm install 时会作为传递依赖自动安装——这在所有 npm 版本上都成立，与 peer 依赖不同。

而 react、mobx 等属于 peer 依赖，存在以下差异：

| 包管理器 | dependencies（如 @ydesign/core） | peerDependencies（如 react） | | --- | --- | --- | | npm 6 及以下 | ✅ 自动安装 | ❌ 不自动安装 | | npm 7+ | ✅ 自动安装 | ✅ 默认自动安装 | | pnpm | ✅ 自动安装 | ⚠️ 通常需在宿主 package.json 中显式声明 |

因此模板显式列出 peer 依赖，但不必写入 @ydesign/core——标准集成场景下，安装 UI 库即可使用，无需关心底层渲染库。

何时需要手动安装 @ydesign/core？

当你的业务代码需要直接引用画布核心 API 时，例如：

import { generateObjectId, Base, type ITemplate } from '@ydesign/core';

请自行添加依赖（pnpm 严格模式下，传递依赖不能在你的源码中直接 import）：

pnpm add @ydesign/core
# 或 npm install @ydesign/core

更多细节见 @ydesign/react-editor · Dependencies。

命令行选项

| 选项 | 说明 | | ----------------------- | ------------------------------------------------------------- | | -t, --template <name> | 指定模板（跳过框架/语言/模板交互），如 react-editor-ts | | --overwrite | 目标目录非空时直接清空后继续 | | --install | 创建后自动安装依赖并启动开发服务器 | | --no-install | 不自动安装，仅生成项目并打印接下来的命令 | | -h, --help | 显示帮助信息 |

自动安装会沿用当前包管理器：npm create ydesign → npm install + npm run dev；yarn create ydesign → yarn + yarn dev；pnpm create ydesign → pnpm install + pnpm dev。

创建后

cd my-editor
npm install     # 如果向导里选了 No
npm run dev

进入项目后，将 src 中 createStore 的 key 替换为你的 YDesign License Key 即可。

本地开发

# 监听模式编译 CLI
pnpm dev

# 构建产物
pnpm build

CLI 通过 tsup 打包为单文件 ESM（dist/index.mjs），index.js 为 bin 入口；模板目录 template-react-* 随包一起发布。