@viewfly/cli

Languages: English

面向 Viewfly 应用的命令行脚手架：在本地快速生成基于 Vite 的 TypeScript 项目；模板含 @viewfly/devtools，并可选集成 @viewfly/router 与 scoped CSS（vite-scoped-css-plugin）。

目录

• 适用场景
• 安装
• 快速开始
• 命令与参数
• 交互式向导说明
• 可选功能详解
• 生成项目里有什么
• 常见问题与排错
• 链接与反馈

适用场景

• 新建一个最小可运行的 Viewfly + Vite 前端工程。
• 需要在一行命令里指定模板、特性、包管理器，便于脚本或 CI 复用。
• 在 CI 里无交互生成固定模板的项目。

安装

全局安装（推荐日常使用）

npm install -g @viewfly/cli

安装后全局命令为 viewfly（见 package.json 的 bin 字段）。

不全局安装：使用 npx

npx @viewfly/cli create my-app

快速开始

viewfly create my-viewfly-app
# 等价别名
viewfly new my-viewfly-app

按提示选择可选特性、包管理器，以及是否在创建后立即安装依赖。完成后进入目录执行开发脚本即可。

cd my-viewfly-app
npm run dev    # 或 pnpm dev / yarn dev，取决于创建项目时选择的包管理器

查看 CLI 自身版本：

viewfly --version
# 或
viewfly -v

查看顶层帮助：

viewfly --help

子命令帮助：

viewfly create --help

命令与参数

viewfly create <name> / viewfly new <name>

在当前工作目录下创建名为 <name> 的子目录，并把模板拷贝到该目录。

| 选项 | 说明 | |------|------| | -t, --template <template> | 模板名称。当前仅内置 vite（默认）。若传入非 vite 且与交互结果不一致时，会通过交互选择（目前选项仍只有 vite）。 | | -f, --features <features> | 逗号分隔的可选特性，见下文 可选功能详解。合法值：router、scoped-css。不传则进入多选交互。 | | --pm <packageManager> | 安装依赖时使用的包管理器：pnpm | npm | yarn。不传则交互选择。 | | --install | 创建完成后立即执行依赖安装。 | | --no-install | 创建完成后跳过安装（仍会打印后续 cd 与手动安装提示）。 | | （未传 install 相关 flag） | 由交互确认「是否现在安装依赖」，默认选「是」。 |

约束与行为（与源码一致）：

• 项目名必填：create 必须带 <name>，否则 CLI 会提示错误并退出该流程。

• 目标目录必须不存在：若 ./<name> 已存在，会取消创建，避免覆盖。

• 非交互 CI 示例：

  viewfly create my-app \
    --template vite \
    --features router,scoped-css \
    --pm pnpm \
    --install

交互式向导说明

在未通过命令行传入对应信息时，CLI 会使用 @inquirer/prompts 依次询问：

1. 模板：当前仅 vite。
2. 可选特性：router、scoped-css（多选）。
3. 包管理器：pnpm / npm / yarn。
4. 是否立即安装依赖：默认为是。

若已通过 flag 提供某项信息，则跳过对应提问（例如已传 --features 则不再出现特性多选）。

可选功能详解

router

• 在生成项目的 package.json 的 dependencies 中加入 @viewfly/router（版本与模板中其他 Viewfly 包保持一致，如 ^3.0.5）。
• 重写 src/main.tsx：入口仍使用 createApp，App 组件文案会提示已启用 Router，便于你在此基础上自行配置路由。

说明：脚手架不会自动生成路由表或文件结构，仅添加依赖与示例文案。

scoped-css

• 生成 src/app.scoped.scss 示例样式。
• 重写 src/main.tsx：改为 import './app.scoped.scss'，不再引用默认的 ./style.css。
• 重写 vite.config.ts：在模板既有 plugins 中追加 …viteScopedCssPlugin()（@viewfly/devtools/vite-scoped-css-plugin）。

可同时指定 router,scoped-css，两者会叠加生效。

生成项目里有什么

模板位于本包的 templates/base-vite，发布时由 package.json 的 files 字段打进 npm 包。

• 构建工具：Vite 8、TypeScript 5.8。
• 开发依赖：@viewfly/devtools（vite.config.ts 中的用法见 @viewfly/devtools）。
• 运行时依赖：@viewfly/core、@viewfly/platform-browser（与 CLI 发布版本线一致，如 ^3.0.5）。
• 占位符：模板中的 package.json 的 name 字段为 __PROJECT_NAME__，创建过程中会替换为你在命令行传入的 <name>。
• 入口：src/main.tsx + index.html，使用 JSX 风格编写 Viewfly 组件。
• 脚本：dev / build / preview 均为标准 Vite 命令。

未启用 scoped-css 时，默认带 src/style.css；启用后由 app.scoped.scss 与 Vite 插件接管样式入口（见上节）。

常见问题与排错

target directory already exists

当前设计不允许覆盖已有目录。请更换项目名，或先删除/移走旧目录。

依赖安装失败

使用 --install 或交互选择安装时，若 pnpm / npm / yarn 返回非零退出码，CLI 会抛出错误。请检查：

• 本机是否已安装所选包管理器；
• 网络与 registry 配置；
• Node 版本是否满足 Vite 与 Viewfly 的要求。

可改用 --no-install，在工程目录内手动排查后再执行安装。

Windows

安装子进程在 Windows 上会使用 shell: true 调用包管理器，一般可正常执行 pnpm install / npm install / yarn。

清屏与 ASCII 横幅

CLI 启动时会 clear 终端并打印 figlet 横幅；在部分 CI 日志环境中可能显得「刷屏」，属预期行为。

链接与反馈

• 官网：https://viewfly.org
• 仓库：https://github.com/viewfly/viewfly
• Issue：https://github.com/viewfly/viewfly/issues

License

MIT（见仓库内 LICENSE 文件）。