VeanUI CLI

vean 是 VeanUI 的命令行工具，用于初始化项目、添加组件、管理 UI 配置与迁移项目。

安装

pnpm add -D @vean/cli

或直接运行：

npx @vean/cli@latest init

命令

vean init

初始化 VeanUI 项目或为现有项目添加配置。

vean init [options]

不提供选项时将进入交互式引导。

vean add

向项目添加组件。

vean add <component...> [options]

vean build

从 registry.json 构建注册表 JSON 文件。

vean build [registry] [options]

vean search

搜索可用组件。

vean search [query] [options]

vean list

列出 registry 中的条目，可按包过滤。

vean list [options]

条目按包命名空间区分（当前为 ui/button、ui/accordion、…；未来外围包遵循 <package>/<component>）。

vean view

查看组件源码。

vean view <component>

vean info

显示项目配置和可用的预设值。

vean info [options]

vean template

从模板快速创建项目。

vean template [name] [options]

可用模板：vue-vite、nuxt。

vean preset

管理配置预设。

vean preset <preset>

vean migrate

把 SoybeanUI 时代的项目（依赖 @soybeanjs/*、或使用 sbean CLI）迁移到 Vean（@vean/*）。

vean migrate [migration] [options]

可用迁移：rebrand（SoybeanUI → Vean）。包名 / import 改写始终生效；运行时契约、CLI 引用、域名三类需显式开启，--new-domain、--new-cdn、--repo-slug 三者各自独立、可单独使用。

vean migrate rebrand                       # 预览
vean migrate rebrand --write               # 落地
vean migrate rebrand -w --runtime-contract --cli --new-domain veanui.com

preflight（先判断该不该迁移）：扫描后先看项目里有没有 SoybeanUI 时代的痕迹——package.json 里的 @soybeanjs/* 依赖、sbean.json、源码里的 @soybeanjs/* 标识符、data-soybean-* / --soybean-* 契约、sbean 调用。都没有（例如目录指错了，或项目已经迁移完）就拒绝执行、退出码 1、不写任何文件；只匹配到旧域名链接时也拒绝，除非你明确传了域名类选项。确实要强制运行用 --force。

运行结束还会给出两组按项目实际情况生成的提示：Worth adding（本次没开启、但项目里确实还有对应改动的开关，如「检测到 12 处 data-soybean-* → 加 --runtime-contract」）与 Still manual（只列真正适用的人工步骤，例如按 package.json 实际依赖拼出的换包命令）。lockfile、node_modules、构建产物与 CHANGELOG.md 永不改写，且命令是幂等的。完整步骤见**品牌迁移指南**。

配置

vean.json 存储项目配置：

{
  "iconLibrary": "lucide",
  "uno": {
    "base": "zinc",
    "primary": "indigo",
    "size": "md",
    "radius": "md"
  },
  "font": {
    "sans": "inter",
    "heading": "inherit"
  },
  "aliases": {
    "ui": "#ui"
  },
  "registries": {}
}

项目结构

单仓库

project/
├── src/
│   └── ui/           ← 组件输出目录 (uiDir)
│       ├── components/
│       ├── styles/
│       ├── theme/
│       ├── constants/
│       ├── resolver/
│       └── nuxt/
├── vean.json
├── tsconfig.json
└── uno.config.ts

Monorepo（pnpm workspaces）

project/
├── packages/
│   └── ui/           ← 组件输出目录 (uiDir)
│       ├── components/
│       ├── styles/
│       ├── theme/
│       ├── constants/
│       ├── resolver/
│       └── nuxt/
├── vean.json
├── tsconfig.json
├── uno.config.ts
└── pnpm-workspace.yaml

别名系统

VeanUI 使用 #ui TypeScript 路径别名进行所有组件导入：

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "#ui/*": ["./src/ui/*"]
    }
  }
}

所有组件导入都使用此命名空间：

import { SButton } from '#ui/components/button';
import { buttonVariants } from '#ui/styles/button';

注册表

Vean 从 VeanUI 注册表获取组件源码，地址为 https://veanui.com/r/<package>/<component>.json——核心 ui 包由 r/ui/{name}.json 提供（如 r/ui/button.json），目录索引在 r/registry.json。注册表条目按包命名空间区分，因此注册表 URL 模板里的 {name} 是带命名空间的条目名（ui/button），而不是裸组件名。核心 ui 组件可省略前缀（vean add button）；未来外围包的组件必须带命名空间前缀（vean add <package>/<component>）。本地缓存（~/.vean/cache）保持 24 小时 TTL 并支持 ETag 条件请求。