@qin-ui/vue-install

@qin-ui/vue-install

一个多功能的 Vue 开发工具集，提供创建各种 Vue 相关项目和组件的命令行工具。

功能特性

• 🌟 交互式界面：友好的命令行交互体验
• 🐉 创建 Vue 应用：完整的 Vue 3 + TypeScript + Vite 项目模板
• 🏗️ 创建 Monorepo 项目：基于 pnpm workspace 的多仓库管理
• 🧱 创建组件：在现有项目中快速创建 Vue 组件（如 MaskText 脱敏组件）
• 🪝 创建 Vue Hook：在项目中添加自定义 Vue 组合式 API（如 useDict 字典 Hook）
• ⚙️ 功能模块：在现有项目中独立安装 Router / Pinia / Axios / i18n / Theme 等
• 📝 统一的代码规范：默认 Oxlint + Oxfmt（极速），可选 ESLint + Prettier，均含 Stylelint + Commitlint

安装方法

使用 npx（推荐）

npx @qin-ui/vue-install

使用 pnpm

pnpm create @qin-ui/vue-install

全局安装

npm install -g @qin-ui/vue-install
vue-install

本地开发

git clone <repository-url>
cd vue-install
pnpm install
pnpm link
vue-install

使用方法

运行工具后，您可以选择以下功能：

🐉 创建 Vue 应用

创建一个功能完整的 Vue 3 + TypeScript + Vite 项目，支持多种自定义配置：

• Vue Router（基于 unplugin-vue-router 的文件系统自动路由）
• Pinia 状态管理
• Axios 请求封装（并发队列调度、自动取消、401 统一处理）
• 多语言支持 (i18n)
• 主题切换 (Theme) - 支持 light / dark / system（跟随系统）
• JSX / TSX 语法支持
• UI 库（Ant Design Vue / Antdv Next / Element Plus / Vant，单选）
• CSS 框架 (Tailwind CSS v4)
• CSS 预处理器 (Less 或 Sass，二选一)
• 自动导入配置
• 完整的开发工具链

⚙️ 添加功能模块

在现有 Vue 项目中添加功能模块，支持按需集成：

• 🧭 Vue Router - 路由管理（基于 unplugin-vue-router 的文件系统路由）
• 🍍 Pinia - 状态管理
• 🌐 Axios - HTTP 请求封装
• 🌐 vue-i18n - 国际化支持
• 🎨 Theme - 主题切换功能
• ⚛️ JSX - JSX / TSX 语法支持
• 🎨 Tailwind CSS - 原子化 CSS 框架
• 📝 Less - CSS 预处理器
• 💅 Sass/SCSS - CSS 预处理器

🏗️ 创建 Monorepo 项目

基于 pnpm workspace 创建多仓库项目结构（apps/pc + apps/h5 + shared）：

• 工作空间管理
• 共享代码包（包名随项目名，如 @my-monorepo/shared）
• 统一的构建流程与代码规范
• 每个子应用独立选择 UI 库

🧱 创建组件

在当前项目中创建 Vue 组件模板（如 MaskText 文本脱敏组件）。

🪝 创建 Vue Hook

创建自定义 Vue 组合式 API（如 useDict 数据字典 Hook，含 getOption/getLabel 辅助方法）。

配置选项

创建 Vue 应用时的配置

• 代码规范: Oxlint + Oxfmt（默认，极速）或 ESLint + Prettier（稳定版）
• 基础功能（多选）: Vue Router / Pinia / Axios / i18n / Theme / JSX
• 样式工具（多选）:
  • Tailwind CSS: 自动配置 Tailwind CSS v4 与暗黑模式（class 模式）
  • Less / Sass: 二选一（两者的 stylelint 预设互相冲突，向导中已互斥）
  • 与 Tailwind CSS 同时使用时，自动处理 stylelint 规则冲突
• UI 组件库（单选）:
  • Ant Design Vue: 含 Layout（侧边栏+头部+面包屑）、ThemeSwitcher、LocaleSwitcher 组件
  • Antdv Next: 复用 Ant Design Vue 的组件模板（包引用自动改写为 antdv-next）
  • Vant: 含移动端 Layout 布局骨架（头部/底部占位，需自行填充内容）
  • Element Plus: 仅安装库与按需引入配置（暂无布局/切换器组件模板）
• Axios: 安装后自动注入并发队列、请求取消、401 跳转与 UI 错误提示集成

功能模块独立安装

在现有项目中，可以独立安装功能模块：

# 运行 vue-install（无参数）
vue-install

# 在交互式菜单中选择 "功能模块" 分类
# 然后选择要添加的功能：
# - 🧭 Vue Router - 路由管理
# - 🍍 Pinia - 状态管理
# - 🌐 Axios - HTTP 请求封装
# - 🌐 国际化 (i18n) - 多语言支持
# - 🎨 主题切换 (Theme) - 主题切换功能
# - ⚛️ JSX 支持
# - 🎨 Tailwind CSS - 原子化 CSS 框架
# - 📝 Less 预处理器 - CSS 预处理器
# - 💅 Sass/SCSS 预处理器 - CSS 预处理器

在 Monorepo 根目录运行时，工具会检测 workspace 并提示选择具体子应用。

生成项目结构

创建的 Vue 应用项目结构（以勾选全部功能为例）：

my-project/
├── src/
│   ├── api/                 # 接口封装（Axios）
│   ├── components/          # 组件目录
│   │   ├── Layout/          # 布局组件（选择 UI 库后安装）
│   │   ├── ThemeSwitcher/   # 主题切换器（Ant Design Vue / Antdv Next）
│   │   └── LocaleSwitcher/  # 语言切换器（Ant Design Vue / Antdv Next）
│   ├── views/               # 页面目录（文件系统自动路由）
│   │   ├── home/            # 主页
│   │   ├── about/           # 关于页
│   │   ├── login/           # 登录页
│   │   └── error/           # 403 / 404 错误页
│   ├── stores/              # 状态管理（可选）
│   ├── i18n/                # 国际化（可选）
│   │   └── locales/         # 语言包目录（zh-CN / zh-TW / en-US）
│   ├── theme/               # 主题切换（可选）
│   ├── router/              # 路由配置（可选）
│   ├── utils/               # 工具（authToken、request 等）
│   ├── assets/              # 静态资源
│   ├── main.ts              # 应用入口
│   └── App.vue              # 根组件
├── public/                  # 公共资源
├── index.html               # HTML 模板
├── package.json
├── vite.config.ts           # Vite 配置
├── tsconfig.json            # TypeScript 配置
├── oxlint.config.ts         # Oxlint 配置（默认方案）
├── .oxfmtrc.json            # Oxfmt 配置（默认方案）
├── stylelint.config.js      # Stylelint 配置
└── .env / .env.development  # 环境变量

选择 ESLint 方案时，配置文件为 eslint.config.ts + prettier.config.js。

开发指南

创建新项目

# 使用 npx 创建项目
npx @qin-ui/vue-install

# 选择 "创建 Vue 应用"
# 按提示选择需要的功能模块

在现有项目中添加功能

# 在项目根目录运行（无参数）
vue-install

# 在交互式菜单中选择 "功能模块" 分类
# 然后选择要添加的功能模块
# 工具会自动检测项目类型并安装相应的功能

项目开发命令

cd my-project
pnpm install          # 安装依赖
pnpm dev              # 启动开发服务器
pnpm build            # 构建生产版本（含 vue-tsc 类型检查）
pnpm preview          # 预览生产版本
pnpm lint             # 代码检查（oxlint 或 eslint）
pnpm lint:style       # 样式检查（stylelint）
pnpm format           # 代码格式化检查（oxfmt --check 或 prettier）
pnpm format:fix       # 代码格式化写入

功能特性说明

主题切换 (Theme)

• 支持 light / dark / system（跟随系统，基于 prefers-color-scheme 实时监听）三种偏好
• 自动持久化用户偏好到 localStorage
• 安装时向 index.html 注入同步主题脚本，避免深色用户刷新闪现亮色（FOUC）
• 安装时向 main.css 注入 :root / :root.dark 主题 CSS 变量（见 theme/README.md）
• 与 Tailwind CSS 集成时使用 dark class（Tailwind dark: 前缀兼容）
• Ant Design Vue / Antdv Next 项目提供 ThemeSwitcher 组件并自动注入 Layout

Axios 请求封装

• 最大并发数控制与请求队列调度，排队请求取消时安全 Reject
• 重复/同路由请求自动取消（abortPrevious）
• 响应式全局 Loading（300ms 防抖）
• 统一业务状态码处理与 401 自动取消请求、跳转登录页
• 错误提示按 UI 库自动集成（Ant Design Vue / Antdv Next / Element Plus / Vant）
• 生成的 src/utils/request 带有 vue-install:managed 标记，自行重写封装时移除该标记即可避免脚手架改写

CSS 预处理器

• Less: 自动配置 stylelint-config-standard-less
• Sass: 自动配置 stylelint-config-standard-scss
• 与 Tailwind CSS 同时使用时，自动处理 stylelint 规则冲突
  • 当 Tailwind CSS 和 Sass 同时存在时，at-rule-no-unknown 设置为 null
  • 使用 scss/at-rule-no-unknown 规则来处理 Tailwind at-rules

代码规范

• 默认方案: Oxlint + Oxfmt（基于 Rust，极速），配置为 TypeScript 文件，oxlint 原生加载
• 可选方案: ESLint 9 Flat Config + Prettier（含 jiti 以支持 .ts 配置）
• Stylelint: CSS/Less/Sass/Vue 样式检查
• Commitlint: Git 提交信息规范
• Husky + lint-staged: Git hooks 管理

许可证

MIT