deedo

A modern console UI/UX toolkit for Node.js

deedo is a modern terminal UI/UX toolkit that helps you craft delightful CLI experiences with zero external dependencies.

deedo 是一个现代化的终端 UI/UX 工具包，提供优雅的组件来创建漂亮的命令行界面。这个名字的灵感来自我的孩子：他每天都在等我回家，还会看动画片，发出deedo 的声音。

✨ Features / 特性

• 🎯 Modern Design / 现代化设计 – Beautiful terminal UI components for CLIs
• 🚀 TypeScript Ready / TypeScript 支持 – Complete type definitions out of the box
• 📦 Zero Dependencies / 零依赖 – Pure Node.js + ANSI escape codes
• 🎨 Rich Components / 组件齐全 – Steps, Progress, Alert, QRCode, Box, Spinner…
• 💬 Interactive Prompts / 交互式提示 – Elegant input experiences
• 🌈 Native Colors / 彩色输出 – Chainable color utilities based on ANSI codes

📦 Install / 安装

Install via npm in one command · 使用 npm 一次安装：

npm install deedo

⚡ Quick Start / 快速开始

Use a few lines to show alerts, steps, and progress bars · 用几行代码快速展示提醒、步骤和进度条：

import { success, steps, progress } from 'deedo';

// 显示成功消息
success('操作完成！');

// 显示步骤进度
steps([
  { title: '登录', status: 'finish' },
  { title: '验证', status: 'finish' },
  { title: '配置', status: 'pending' },
]);

// 显示进度条
const bar = progress({ total: 100 });
bar.update(50);

📚 Components / 组件文档

Alert / 提示

Display different alert states · 显示不同类型的提示信息：

import { success, info, warning, error } from 'deedo';

success('操作成功！');
info('这是一条信息');
warning('请注意！');
error('发生错误！');

Info Labels / 信息标签

Use background labels for build logs and CLI output · 带背景色的信息标签，适用于构建工具、CLI 工具的日志输出：

import { INFO, SUCCESS, ERROR, WARNING } from 'deedo';

// 直接使用标签常量
const resolvedOutPath = '/export/file/resource';
console.log(`${INFO} 输出目录: ${resolvedOutPath}/`);
console.log(`${INFO} 打包完成，上传到服务器`);
console.log(`${SUCCESS} 部署成功！`);
console.log(`${WARNING} 请注意配置文件版本`);
console.log(`${ERROR} 连接失败，请重试`);

// 或使用辅助函数
import { logInfo, logSuccess, logError, logWarning } from 'deedo';

logInfo('开始处理文件...');
logSuccess('处理完成！');
logWarning('发现警告');
logError('发现错误');

可用标签：

• INFO - 绿色背景（默认）
• INFO_CYAN - 青色背景
• INFO_BLUE - 蓝色背景
• SUCCESS - 绿色背景
• WARNING - 黄色背景
• ERROR - 红色背景

See more: Info Labels guide · 查看完整文档：Info Labels 文档

Steps / 步骤条

Render process flows with Ant Design–style data (title/content) · 显示多步骤流程，数据结构与 Ant Design 类似，并且可以传入函数来自定义渲染：

import { steps, colors } from 'deedo';

steps([
  { title: '登录', content: '用户已认证', status: 'finish' },
  { title: '验证', content: '验证码已确认', status: 'finish' },
  { title: '配置', content: '正在设置...', status: 'pending' },
  {
    title: () => colors.success('部署完成！'),
    content: () => colors.dim('title/content 函数需要返回字符串'),
  },
]);

支持的状态：'success' | 'error' | 'warning' | 'info' | 'pending' | 'finish'（默认：pending）

💡 提示：当 title / content 传入函数时，请返回一个字符串（例如 () => colors.success('...')）。不要在函数里直接调用会输出日志的 API（如 success()），否则无法保持对齐。

Progress / 进度条

Display task progress with customizable bars · 显示任务进度：

import { progress } from 'deedo';

const bar = progress({ 
  total: 100, 
  width: 40,
  format: ':bar :percent :current/:total'
});

// 更新进度
bar.update(50);

// 增加进度
bar.tick(10);

// 完成
bar.complete();

Interactive Prompts / 交互式提示

Text Input / 文本输入

import { text } from 'deedo';

const name = await text({
  message: '你的名字是？',
  initial: 'User'
});

Select / 选择器

import { select } from 'deedo';

const framework = await select({
  message: '选择一个框架：',
  choices: [
    { value: 'react', label: 'React', hint: 'JavaScript 库' },
    { value: 'vue', label: 'Vue', hint: '渐进式框架' },
    { value: 'angular', label: 'Angular', hint: '应用平台' },
  ],
  initial: 0
});

Confirm / 确认

import { confirm } from 'deedo';

const shouldContinue = await confirm('是否继续？', true);

Spinner / 加载动画

Display async status with elegant spinners · 显示加载状态：

import { spinner } from 'deedo';

const spin = spinner('正在安装依赖...');
spin.start();

// 模拟异步操作
await someAsyncTask();

// 成功完成
spin.succeed('依赖安装完成！');

// 或失败
// spin.fail('安装失败！');

// 或直接停止
// spin.stop();

Box / 边框容器

Render bordered content blocks with multilingual & emoji support · 在边框内显示内容，完美支持多语言和 Emoji：

import { box } from 'deedo';

box(
  '欢迎使用 deedo！\n现代化的终端 UI 工具包\n适用于 Node.js 应用',
  { 
    title: '欢迎', 
    padding: 2, 
    borderColor: 'success' 
  }
);

// 支持多语言混合
box(
  '中文：你好世界\n日本語：こんにちは\n한국어：안녕하세요\nEnglish: Hello\n🎉 Emoji: 🚀 ✨',
  { title: 'Multi-language Support', borderColor: 'info' }
);

特性：

• ✅ 自动计算全角字符宽度（中文、日文、韩文等）
• ✅ 正确处理 Emoji 显示宽度
• ✅ 支持混合语言内容
• ✅ 支持带颜色的文本
• ✅ 自动对齐不同长度的行

🎯 Full Example / 完整示例

Vite-style Scaffold / Vite 风格脚手架

Mimic npm create vite@latest interactions with rich prompts · 模拟 npm create vite@latest 的完整交互体验：

import {
  text,
  select,
  confirm,
  spinner,
  steps,
  success,
} from 'deedo';

async function scaffold() {
  // 项目名称
  const projectName = await text({
    message: '项目名称：',
    initial: 'my-app',
  });

  // 选择框架
  const framework = await select({
    message: '选择框架：',
    choices: [
      { value: 'vanilla', label: 'Vanilla', hint: '纯 JavaScript' },
      { value: 'react', label: 'React', hint: 'JavaScript 库' },
      { value: 'vue', label: 'Vue', hint: '渐进式框架' },
    ],
  });

  // 确认安装
  const shouldInstall = await confirm('立即安装依赖？');

  // 显示进度
  const spin = spinner('正在创建项目...');
  spin.start();
  await createProject(projectName, framework);
  spin.succeed('项目创建完成！');

  if (shouldInstall) {
    const installSpin = spinner('正在安装依赖...');
    installSpin.start();
    await installDependencies();
    installSpin.succeed('依赖安装完成！');
  }

  // 显示完成步骤
  steps([
    { title: '项目创建', status: 'finish' },
    { title: '依赖安装', status: shouldInstall ? 'finish' : 'pending' },
    { title: '准备就绪', status: 'finish' },
  ]);

  success('完成！现在运行：');
  console.log(`  cd ${projectName}`);
  console.log('  npm run dev');
}

🛠️ Development / 开发

Useful scripts for hacking on deedo · 常用开发脚本：

# 安装依赖
npm install

# 构建
npm run build

# 监听模式
npm run dev

# 运行示例
npm run example

📖 Examples / 示例

The repo ships with two demos · 项目自带两个示例文件：

• examples/demo.js - 所有组件的基础演示
• examples/vite-style-demo.js - Vite 风格的交互式脚手架演示

Run the demos · 运行示例：

# 构建项目
npm run build

# 运行基础演示
node examples/demo.js

# 运行 Vite 风格演示
node examples/vite-style-demo.js

🎨 Styling / 样式自定义

deedo relies on ANSI codes—use the color helpers directly · 使用内置颜色工具来自由搭配 ANSI 样式：

import { colors, icons } from 'deedo';

console.log(colors.success('成功文本'));
console.log(colors.error('错误文本'));
console.log(colors.warning('警告文本'));
console.log(colors.info('信息文本'));
console.log(colors.cyan('青色文本'));
console.log(colors.bold('粗体文本'));
console.log(colors.dim('暗淡文本'));

// 支持链式调用
console.log(colors.bold.cyan('粗体青色文本'));
console.log(colors.bold.green('粗体绿色文本'));

console.log(icons.success); // ✔
console.log(icons.error);   // ✖
console.log(icons.warning); // ⚠
console.log(icons.info);    // ℹ

📄 License / 许可证

MIT © Gary

🤝 Contributing / 贡献

Issues and PRs are welcome · 欢迎提交 Issue 和 Pull Request！

🌟 Benefits / 优势

• Zero dependencies / 零依赖 – No third-party packages, tiny footprint
• Native implementation / 原生实现 – Pure Node.js + ANSI escape codes
• High performance / 高性能 – Minimal startup overhead
• Easy maintenance / 易维护 – Simple, modular TypeScript code
• Multilingual support / 多语言支持 – Handles CJK + Emoji perfectly
• Smart alignment / 智能对齐 – Accurate width calculation for mixed text

🔗 Related Projects / 相关项目

• clack – CLI prompts tool · CLI 提示工具
• inquirer – Interactive CLI · 交互式命令行工具
• ora – Elegant spinner · 优雅的终端 spinner