npm package: @qin-ui/vue-install
Description: Create a new Vue 3 project with customizable features
Author: dufan3715
Latest version: 0.1.8

# @qin-ui/vue-install

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

## 功能特性

- 🌟 交互式界面：友好的命令行交互体验
- 🐉 创建 Vue 应用：完整的 Vue 3 + TypeScript + Vite 项目模板
- 🏗️ 创建 Monorepo 项目：基于 pnpm workspace 的多仓库管理
- 🧱 创建组件：在现有项目中快速创建 Vue 组件
- 🛠️ 创建工具函数：在项目中添加实用工具函数
- 🪝 创建 Vue Hook：在项目中添加自定义 Vue 组合式 API
- 📄 创建示例页面：在项目中添加示例展示页面
- 📝 统一的代码规范：ESLint + Prettier + Stylelint + Commitlint

## 安装方法

### 使用 npx（推荐）

```bash
npx @qin-ui/vue-install
```

### 使用 pnpm

```bash
pnpm create @qin-ui/vue-install
```

### 全局安装

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

### 本地开发

```bash
git clone <repository-url>
cd frontend-template
pnpm install
pnpm link
vue-install
```

## 使用方法

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

### 🐉 创建 Vue 应用

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

- Vue Router（Vue Router 5 内置的文件系统自动路由）
- Pinia 状态管理
- 多语言支持 (i18n)
- 主题切换 (Theme) - 支持 light/dark 模式
- UI 库 (Ant Design Vue 或 Element Plus)
- CSS 框架 (Tailwind CSS)
- CSS 预处理器 (Less 或 Sass)
- 自动导入配置
- 完整的开发工具链

### 🔧 添加功能模块

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

- 🧭 Vue Router - 路由管理（Vue Router 5 自带文件系统路由）
- 🍍 Pinia - 状态管理
- 🌐 vue-i18n - 国际化支持
- 🎨 Theme - 主题切换功能
- 🎨 Tailwind CSS - 原子化 CSS 框架
- 📝 Less - CSS 预处理器
- 💅 Sass/SCSS - CSS 预处理器

### 🏗️ 创建 Monorepo 项目

基于 pnpm workspace 创建多仓库项目结构：

- 工作空间管理
- 共享依赖
- 统一的构建流程

### 🧱 创建组件

在当前项目中创建 Vue 组件模板：

- 基于 TypeScript
- 包含样式文件
- 自动添加导出

### 🛠️ 创建工具函数

在项目中添加工具函数：

- TypeScript 支持
- 包含单元测试模板
- 自动添加到 utils 目录

### 🪝 创建 Vue Hook

创建自定义 Vue 组合式 API：

- TypeScript 支持
- 包含使用示例
- 遵循组合式 API 最佳实践

### 📄 创建示例页面

在项目中添加示例页面：

- 完整页面模板
- 路由配置示例
- 样式适配

## 配置选项

### 创建 Vue 应用时的配置

创建 Vue 应用时，可选择以下配置：

- **Vue Router**: 是否安装 Vue Router（启用后自动配置基于文件系统的路由生成）
- **Pinia**: 是否启用 Pinia 状态管理
- **i18n**: 是否使用国际化支持
- **Theme**: 是否启用主题切换功能（light/dark）
  - 与 Tailwind CSS 集成时，自动使用 Tailwind 的暗黑模式
  - 支持 Ant Design Vue 和 Element Plus 的主题切换
- **Tailwind CSS**: 是否安装原子化 CSS 框架
  - 自动配置暗黑模式支持
  - 与 Sass 同时使用时，自动处理 stylelint 配置冲突
- **CSS 预处理器**: None / Less / Sass
  - Less: 自动配置 stylelint-config-standard-less
  - Sass: 自动配置 stylelint-config-standard-scss
  - 与 Tailwind CSS 同时使用时，自动处理规则冲突
- **UI 库**: None / Ant Design Vue / Element Plus
  - Ant Design Vue: 包含完整的布局组件和主题配置
  - Element Plus: 包含完整的布局组件和主题配置

### 功能模块独立安装

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

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

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

## 生成项目结构

创建的 Vue 应用项目结构：

```
my-project/
├── src/
│   ├── components/        # 组件目录
│   ├── views/            # 页面目录（传统路由）
│   │   ├── home/         # 主页
│   │   ├── about/        # 关于页
│   │   ├── login/        # 登录页
│   │   └── 404/          # 404页面
│   ├── stores/           # 状态管理（可选）
│   ├── i18n/             # 国际化（可选）
│   │   ├── locales/      # 语言文件
│   │   │   ├── en-US.ts
│   │   │   ├── zh-CN.ts
│   │   │   └── zh-TW.ts
│   │   └── index.ts
│   ├── theme/            # 主题切换（可选）
│   │   ├── index.ts      # 主题工具函数
│   │   └── useTheme.ts   # useTheme hook
│   ├── router/           # 路由配置（可选）
│   ├── layout/           # 布局组件（可选）
│   ├── assets/           # 静态资源
│   ├── main.ts           # 应用入口
│   └── App.vue           # 根组件
├── public/               # 公共资源
├── index.html            # HTML 模板
├── package.json
├── vite.config.ts        # Vite 配置
├── tsconfig.json         # TypeScript 配置
├── eslint.config.ts      # ESLint 配置（主项目）
├── stylelint.config.js   # Stylelint 配置
└── prettier.config.js    # Prettier 配置
```

## 开发指南

### 创建新项目

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

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

### 在现有项目中添加功能

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

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

### 项目开发命令

```bash
cd my-project
pnpm install          # 安装依赖
pnpm dev              # 启动开发服务器
pnpm build            # 构建生产版本
pnpm preview          # 预览生产版本
pnpm lint             # 代码检查
pnpm lint:style       # 样式检查
pnpm format           # 代码格式化
pnpm type-check       # 类型检查
```

## 功能特性说明

### 主题切换 (Theme)

- 支持 light/dark 两种模式
- 自动持久化用户偏好到 localStorage
- 与 Tailwind CSS 集成时，使用 Tailwind 的暗黑模式类选择器
- 支持 Ant Design Vue 和 Element Plus 的主题切换
- 提供 `useTheme` hook 方便在组件中使用

### Tailwind CSS 集成

- 自动配置 Tailwind CSS v4
- 配置暗黑模式支持（使用类选择器）
- 自动处理与 Sass 的 stylelint 配置冲突
- 集成 Prettier 插件，自动排序 Tailwind 类名

### 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

### 代码规范

- **ESLint**: 基于 @eslint/js 和 TypeScript ESLint
- **Prettier**: 统一的代码格式化
- **Stylelint**: CSS/Less/Sass 样式检查
- **Commitlint**: Git 提交信息规范
- **Husky**: Git hooks 管理

## 许可证

MIT