ui-comp-cli

一个用于管理和添加多个 UI 组件库到项目的 CLI 工具。内置完整组件库，零配置，开箱即用！

✨ 功能特性

• 🚀 快速添加组件 - 通过简单命令添加 UI 组件到 src/components 目录
• 🎨 完整模板支持 - 导入完整的 Next.js 应用模板到当前工作目录
• 📦 多 UI 库支持 - 同时支持 Aceternity UI Pro、Magic Pro 和 Saas
• 🎭 19+ 完整模板 - 从模板快速启动项目
• 💻 交互式界面 - 美观的命令行交互
• 🔧 TypeScript 支持 - 完整的类型支持
• 📝 配置持久化 - 保存项目配置
• 🎯 智能扫描 - 自动发现可用组件和 UI 库
• ✨ 内置组件库 - v2.0 新特性，无需配置本地路径
• 🎊 零配置 - 安装后立即可用
• 🔌 可扩展 - 支持多个 UI 组件库，随时可添加新库

🎬 快速开始

安装

方式 1：全局安装（推荐）

npm install -g ui-comp-cli
# 或
pnpm add -g ui-comp-cli

方式 2：项目局部安装

npm install --save-dev ui-comp-cli
# 或
pnpm add -D ui-comp-cli

方式 3：本地开发

# 克隆或进入项目
cd /path/to/ui-comp-cli

# 安装依赖
pnpm install

# 编译
pnpm build

# 全局链接（开发模式）
pnpm link --global

2 步开始使用

第 1 步：初始化（可选）

在你的项目目录运行：

ui init

这会自动创建 src/components/ui 目录，无需任何配置。

输出示例：

🎨 Welcome to ui-comp-cli!

✨ Setup complete!

Components directory: src/components/ui
Templates directory: current directory (root)

Next steps:
  1. Run ui list to see available components
  2. Run ui add to add a component
  3. Run ui add --template to add a template

第 2 步：添加组件或模板

查看可用组件：

ui list

输出示例：

📦 Available Components:

━━━ Aceternity UI Pro ━━━

  backgrounds:
    • background-with-dots-masked.tsx
    • background-with-skewed-rectangles.tsx
    • ...

  hero:
    • hero-1.tsx
    • hero-2.tsx
    • ...

━━━ Magic Pro ━━━

  templates:
    • agent-template
    • saas-template
    • ...

Total: 100+ components from 3 UI libraries

🎨 Available Templates:

━━━ Aceternity UI Pro ━━━

  • ai-saas-template
  • agenlabs-agency-template
  • ...

━━━ Magic Pro ━━━

  • agent-template
  • devtool-template
  • mobile-template
  • saas-template
  • startup-template

━━━ Saas ━━━

  • MkSaas
  • ShipAny one

Total: 19+ templates from 3 UI libraries

添加组件：

ui add

按提示选择：

1. 选择 UI 库（如 Aceternity UI Pro 或 Magic Pro）
2. 选择组件分类（如 backgrounds）
3. 选择具体组件（如 background-with-dots-masked.tsx）

组件会自动复制到 src/components/ui/{UI库名}/{分类}/ 目录！

📚 命令说明

ui init

初始化项目，创建组件目录。

ui init

这个命令会：

• 自动创建 src/components/ui 目录
• 无需任何配置或询问
• 可选执行（直接运行 ui add 也会自动创建目录）

ui list

列出所有可用的组件和模板。

# 列出所有
ui list

# 只列出组件
ui list --components

# 只列出模板
ui list --templates

ui add

添加组件到项目。

# 交互式添加组件
ui add

# 添加模板
ui add --template

# 指定组件和分类
ui add <component-name> --category <category>

📦 支持的 UI 组件库

🎨 Aceternity UI Pro

组件分类（19 种）：

• ✨ backgrounds - 背景效果组件（15+ 个）
• 📦 bento-grids - Bento 网格布局（3 个）
• 📝 blog-content-sections - 博客内容区块（2 个）
• 📝 blog-sections - 博客区块（2 个）
• 🃏 cards - 卡片组件（4 个）
• 📧 contact-sections - 联系区块（2 个）
• 🎯 cta-sections - 行动号召区块（3 个）
• ❓ faq - 常见问题组件（3 个）
• ⭐ feature-sections - 特性展示区块（4 个）
• 🦶 footers - 页脚组件（3 个）
• 🦸 hero - 英雄区块（8 个）
• 🔐 login-and-signup - 登录注册表单（2 个）
• 🏢 logo-clouds - Logo 云展示（3 个）
• 🧭 navbars - 导航栏（2 个）
• 💰 pricing-sections - 定价表区块（3 个）
• 📊 sidebars - 侧边栏（2 个）
• 📈 stats-sections - 统计数据区块（4 个）
• 💬 testimonials - 用户评价（3 个）
• ✍️ text-animations - 文字动画（3 个）

模板（12 个）：

• ✨ ai-saas-template - AI SaaS 应用模板
• 🏢 agenlabs-agency-template - 代理机构模板
• 💼 cryptgen-marketing-template - 加密货币营销模板
• 🚀 devpro-portfolio-template - 开发者作品集模板
• 🎨 foxtrot-marketing-template - 营销模板
• 💼 minimal-portfolio-template - 极简作品集
• 🤖 nodus-agent-template - AI 代理模板
• 🎪 playful-marketing-template - 趣味营销模板
• 📊 proactiv-marketing-template - 主动营销模板
• 📅 schedule-marketing-template - 日程营销模板
• 📱 sidefolio-portfolio-template - 侧边栏作品集
• 🚀 startup-landing-page-template - 启动页模板

✨ Magic Pro

模板（5 个）：

• 🤖 agent-template - AI 代理模板
• 🛠️ devtool-template - 开发工具模板
• 📱 mobile-template - 移动端展示模板
• 💼 saas-template - SaaS 应用模板
• 🚀 startup-template - 创业公司模板

🚀 Saas

模板（2+ 个）：

• 📦 MkSaas - 功能完整的 SaaS 应用模板（包含支付、邮件、多语言等）
• ⚡ ShipAny one - 快速启动 SaaS 项目模板
• 🚢 ShipFast - （即将推出）
• ⚙️ SupaStarter - （即将推出）

🔌 扩展性

CLI 工具会自动扫描 UI/ 目录下的所有子目录，支持动态添加新的 UI 组件库。只需在 UI/ 目录下添加新的组件库文件夹，遵循以下结构：

UI/
├── Your New UI Library/
│   ├── component-packs/     # 组件分类（可选）
│   │   ├── category-1/
│   │   │   ├── component-1.tsx
│   │   │   └── component-2.tsx
│   │   └── category-2/
│   └── templates/           # 完整模板（可选）
│       ├── template-1/
│       └── template-2/

CLI 会自动识别并在命令中提供选择。

注意事项：

• 空文件夹会被自动忽略，不会在列表中显示
• 支持同时包含 component-packs 和 templates，也可以只包含其中一个
• 目录名称会作为 UI 库的显示名称

🎯 使用示例

示例 1: 添加 Aceternity UI Pro 背景效果

# 添加背景组件
ui add
# 1. 选择 UI 库: Aceternity UI Pro
# 2. 选择分类: backgrounds
# 3. 选择组件: background-with-dots-masked.tsx

在代码中使用：

// app/page.tsx
import { BackgroundWithDotsMasked } from '@/components/ui/Aceternity UI Pro/backgrounds/background-with-dots-masked';

export default function Page() {
  return (
    <div className="relative min-h-screen">
      <BackgroundWithDotsMasked />
      <div className="relative z-10">
        <h1>Welcome to My App</h1>
      </div>
    </div>
  );
}

示例 2: 添加 Magic Pro 模板

# 创建新项目目录
mkdir my-agent-app
cd my-agent-app

# 添加模板
ui add --template
# 1. 选择 UI 库: Magic Pro
# 2. 选择模板: agent-template
# 3. 确认复制到当前目录

# 安装依赖并运行
pnpm install
pnpm dev

示例 3: 混合使用多个 UI 库

# 在同一个项目中使用多个 UI 库的组件

# 添加 Aceternity UI Pro 的 Hero
ui add
# 选择: Aceternity UI Pro → hero → hero-1.tsx

# 添加 Magic Pro 的组件（如果有 component-packs）
ui add
# 选择: Magic Pro → ... → ...

# 组件会分别保存在不同的目录下
# src/components/ui/Aceternity UI Pro/hero/hero-1.tsx
# src/components/ui/Magic Pro/.../...

⚙️ 默认配置

ui-comp-cli 使用约定优于配置的理念，无需任何配置文件：

| 项目 | 默认值 | 说明 | |------|--------|------| | 组件目录 | src/components/ui | 组件会自动添加到此目录 | | 模板目录 | 当前工作目录 | 模板会复制到项目根目录 | | TypeScript | 支持 | 自动识别 .tsx/.jsx 文件 |

特点：

• ✨ 零配置：无需创建任何配置文件
• 🚀 开箱即用：安装后立即可用
• 📦 约定优于配置：遵循最佳实践的默认设置

🏗️ 项目结构

ui-comp-cli/
├── src/                              # TypeScript 源代码
│   ├── cli.ts                       # CLI 入口
│   ├── commands/                    # 命令实现
│   │   ├── init.ts                 # 初始化命令
│   │   ├── add.ts                  # 添加组件/模板命令
│   │   └── list.ts                 # 列表命令
│   └── utils/                       # 工具函数
│       ├── config.ts               # 配置管理（支持多 UI 库）
│       ├── registry.ts             # 组件注册（动态扫描）
│       └── copy.ts                 # 文件复制
├── dist/                             # 编译输出
├── UI/                               # 内置组件库（v2.0+）
│   ├── Aceternity UI Pro/           # Aceternity UI Pro 组件库
│   │   ├── component-packs/        # 19 个组件分类
│   │   │   ├── backgrounds/
│   │   │   ├── hero/
│   │   │   ├── pricing-sections/
│   │   │   └── ...
│   │   └── templates/              # 12 个完整模板
│   │       ├── ai-saas-template/
│   │       ├── minimal-portfolio-template/
│   │       └── ...
│   ├── Magic Pro/                   # Magic Pro 组件库
│   │   └── templates/              # 5 个完整模板
│   │       ├── agent-template/
│   │       ├── saas-template/
│   │       └── ...
│   └── Saas/                        # Saas 模板库
│       └── templates/              # 2+ 个完整模板
│           ├── MkSaas/
│           ├── ShipAny one/
│           └── ...
├── examples/                         # 示例文件
├── scripts/                          # 脚本
└── README.md

注：
- UI 目录支持多个组件库，会自动扫描所有子目录
- 可随时添加新的 UI 库，无需修改代码
- 每个 UI 库可以包含 component-packs 和/或 templates

🔧 开发

本地开发

# 安装依赖
pnpm install

# 监听模式（自动编译）
pnpm dev

# 手动编译
pnpm build

# 测试
ui --version

调试

在项目中添加 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug CLI",
      "program": "${workspaceFolder}/dist/cli.js",
      "args": ["add"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    }
  ]
}

🎓 最佳实践

1. 组件命名

添加组件后，建议重命名为更具语义的名称：

# 复制后
src/components/ui/hero/hero-1.tsx

# 重命名为
src/components/ui/hero/landing-hero.tsx

2. 自定义样式

组件添加到项目后，可以自由修改：

// 修改前
export default function Hero() {
  return <div className="bg-black">...</div>
}

// 修改后
export default function Hero() {
  return <div className="bg-gradient-to-r from-blue-500 to-purple-500">...</div>
}

3. 批量添加

如果需要多个组件，连续运行：

ui add  # 添加 hero
ui add  # 添加 features  
ui add  # 添加 pricing

4. 版本控制

建议将添加的组件提交到 git：

git add src/components/ui/
git commit -m "Add UI components via ui-comp-cli"

5. 团队协作

在 package.json 中添加：

{
  "devDependencies": {
    "ui-comp-cli": "^1.0.2"
  },
  "scripts": {
    "ui:init": "ui init",
    "ui:list": "ui list",
    "ui:add": "ui add"
  }
}

团队成员可以这样使用：

pnpm install
pnpm ui:list
pnpm ui:add

6. 组件 vs 模板的区别

组件（Component Packs）：

• 单个 UI 组件文件（.tsx / .jsx）
• 添加到 src/components 目录下
• 可以在项目的任何地方导入使用
• 适合增强现有项目

模板（Templates）：

• 完整的 Next.js 应用
• 包含 app/、components/、public/ 等完整目录结构
• 直接复制到当前工作目录
• 适合快速启动新项目
• 添加前会提示确认目录位置

⚠️ 常见问题

Q: 需要下载 Aceternity UI Pro 吗？

A: 不需要！ui-comp-cli 自带完整组件库，开箱即用。

Q: 如何更新组件库？

A: 更新 ui-comp-cli 版本即可：

npm update -g ui-comp-cli

Q: 可以修改添加的组件吗？

A: 可以！组件复制到项目后，你拥有完全的控制权，可以随意修改。

Q: 如何在现有项目中使用？

A: 直接运行 ui add 即可，会自动创建 src/components/ui 目录。ui init 是可选的。

Q: 支持哪些框架？

A: 主要支持 React 和 Next.js，组件使用 TypeScript 和 Tailwind CSS。

Q: 组件和模板有什么区别？

A:

• 组件：单个 UI 组件，添加到 src/components 目录，用于增强现有项目
• 模板：完整的 Next.js 应用，直接复制到当前工作目录，用于快速启动新项目

Q: 为什么添加模板需要确认？

A: 因为模板是完整的应用，会在当前目录创建 app/、components/、public/ 等文件夹。确认步骤是为了防止误操作覆盖文件。

Q: 可以添加其他 UI 组件库吗？

A: 可以！UI 目录支持多个组件库。只需在 UI/ 目录下添加新的组件库文件夹，CLI 会自动识别。

遵循以下结构：

UI/
└── Your New UI Library/
    ├── component-packs/     # 可选
    │   └── category-name/
    │       └── component.tsx
    └── templates/           # 可选
        └── template-name/

无需修改任何代码，CLI 会在下次运行时自动发现新库。

Q: 找不到 ui 命令？

# 重新链接
cd /path/to/ui-comp-cli
pnpm link --global

# 验证
which ui

Q: 需要配置文件吗？

A: 不需要！ui-comp-cli 采用零配置设计，无需任何配置文件即可使用。

Q: 权限问题？

如果遇到权限问题，尝试：

sudo pnpm link --global

📝 更新日志

[2.1.0] - 2024-11-19

新增功能

• 🚀 新增 Saas 模板库 - 添加 Saas 模板库支持（MkSaas、ShipAny one 等）
• ✨ 空目录过滤 - 自动过滤空文件夹，不显示未完成的模板
• 📦 更好的扩展性 - 优化了目录扫描逻辑，支持更灵活的目录结构

[2.0.0] - 2024-11-18

重大变更

• 🎉 多 UI 库支持 - 同时支持多个 UI 组件库
• ✨ 动态库扫描 - 自动发现 UI 目录下的所有组件库
• 📦 新增 Magic Pro - 添加 Magic Pro 组件库支持
• 🔄 目录结构优化 - 组件按 UI 库分类存储

新增功能

• 🎯 UI 库选择界面 - 添加组件/模板时可选择 UI 库
• 📊 分组显示 - list 命令按 UI 库分组展示
• 🔌 完全可扩展 - 支持随时添加新 UI 库，无需修改代码
• 📁 智能目录管理 - 自动创建 UI库名/分类/ 结构

技术变更

• 在 config.ts 中添加 getAllUILibraries() 函数
• 更新 Component 和 Template 接口，添加 library 字段
• 重构 registry.ts 支持多库扫描
• 优化 add.ts 和 list.ts 的交互流程
• 更新 copy.ts 支持 UI 库路径

破坏性变更

• 组件目录结构从 src/components/ui/{category}/ 改为 src/components/ui/{library}/{category}/
• 导入路径需要包含 UI 库名称

[1.0.2] - 2024-11-17

变更

• 📦 包名更新为 ui-comp-cli
• 🔧 CLI 命令简化为 ui
• 🎯 零配置设计 - 移除所有配置文件和询问
• ✨ 约定优于配置 - 使用固定的默认路径
• 📝 更新文档

[1.0.0] - 2024-11-17

新增

• 🎉 ui-comp-cli 初始版本
• ✨ init 命令用于项目初始化
• ✨ add 命令用于添加组件和模板
• ✨ list 命令用于查看可用组件
• 📦 支持 Aceternity UI Pro 组件
• 🎨 支持完整模板导入
• 🎯 零配置设计
• 🔧 TypeScript 支持
• 📝 交互式 CLI 提示
• 🎯 基于分类的组件组织
• 🚀 全局 CLI 工具安装
• ✨ 内置 UI 组件库 - 无需配置源目录
• 🎯 零配置 - 安装后立即可用
• 📦 自包含 - 所有组件和模板包含在包中

技术变更

• 在 config.ts 中添加了 getCliRootDir() 和 getBuiltinUIDir() 函数
• 更新了 registry.ts 以从内置 UI 目录读取
• 修改了 init.ts 以移除源目录提示
• 更新了 package.json 的 files 配置

移除

• ❌ 不再需要本地 Aceternity UI Pro 目录
• ❌ 移除了源目录路径配置

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE

🙏 致谢

• Aceternity UI Pro - 组件来源
• Commander.js - CLI 框架
• Prompts - 交互式提示
• chalk - 终端颜色
• ora - 加载动画

版本: 2.1.0

状态: ✅ 生产就绪

创建日期: 2024-11-17

最后更新: 2024-11-19

祝你使用愉快！🎉