# create-vite-ts-pkg

[![NPM Version](https://img.shields.io/npm/v/create-vite-ts-pkg.svg)](https://www.npmjs.com/package/create-vite-ts-pkg)
[![NPM Downloads](https://img.shields.io/npm/dt/create-vite-ts-pkg.svg)](https://www.npmjs.com/package/create-vite-ts-pkg)
[![License](https://img.shields.io/npm/l/create-vite-ts-pkg.svg)](https://github.com/iss-tools/create-vite-ts-pkg/blob/main/LICENSE)

[English](./README.md) | [简体中文](./README.zh-CN.md)

一个强大、交互式、全能的通用脚手架 CLI 工具，用于基于 **TypeScript** 和 **Vite** 快速生成 NPM 组件库和 Web 应用。

## 为什么选择本工具？

与其为不同的前端框架维护繁杂的多个模板仓库，不如使用这个脚手架动态生成符合你需求的初始代码。通过简单的交互式命令行，你可以一键生成：
- 纯 Vanilla TypeScript 代码包/应用
- Vue 3 组件库/应用
- React 组件库/应用
- Svelte 组件库/应用
- Solid 组件库/应用

不仅如此，脚手架还能智能识别你选择的底层框架，并允许你在下一步**自动集成流行的 UI 组件库**（如 Element Plus, Ant Design, Material UI, Vant 等），开箱即用！

## 核心特性

- **交互式选择**：按需动态选择你的项目类型 (库/Web应用)、JavaScript 框架、对应的 UI 库，以及 CSS 预处理器（Sass/Less）和 CSS 框架（UnoCSS/TailwindCSS）。
- **Vite 引擎驱动**：预置了完备的 Vite 打包流水线，支持一键产出库的 `ESM`, `CJS`, `UMD`, `IIFE` 格式，并利用 `vite-plugin-dts` 生成 `index.d.ts` 类型声明文件。
- **智能依赖注入**：脚手架会根据你的选择，在后台动态地注入对应的 Vite 编译插件（如 `@vitejs/plugin-vue`, `@vitejs/plugin-react` 等），并自动写入 `peerDependencies` 和 `devDependencies`。
- **零配置 TSX/JSX**：自动为 React 或 Solid 项目重写 `tsconfig.json` 的解析规则。
- **内置可视化 Playground**：生成的所有项目均自动集成了一个微型的 Vite 游乐场，只需运行 `pnpm dev` 即可在浏览器中实时开发和预览你的 UI 组件。
- **开箱即用的组件测试**：针对你选择的框架，自动配置好 Jest 组件渲染测试（完美处理测试库注入与复杂的 ESM 解析问题）。
- **内置工程化规范**：生成的所有项目均已默认集成 Jest 测试框架、ESLint、Prettier、Husky、Commitlint，以及用于全自动发版的 `release-it` 工具。

## 如何使用

无须全局安装，使用 `npx`、`pnpm create` 或 `yarn create` 立即初始化一个新项目：

```bash
npx create-vite-ts-pkg my-component-library
# 或者
pnpm create ts-pkg@latest my-component-library
# 或者
yarn create ts-pkg@latest my-component-library
```

### 静默 / 非交互模式

如果你希望在脚本中全自动运行，可以直接通过参数一键创建，完全跳过所有交互提示：

```bash
npx create-vite-ts-pkg --name=my-app --type=library --js=vue --ui=element-plus
```

支持的参数：
- `--name`: 项目名称。
- `--type`: 项目类型 (`library`, `web`)。
- `--js`: 底层 JS 框架 (`none`, `vue`, `react`, `svelte`, `solid`)。
- `--ui`: 前端 UI 框架 (`none`, `element-plus`, `ant-design-vue`, `vant`, `antd`, `@mui/material`, `sveltestrap`, `@suid/material`)。
- `--css`: CSS 预处理器 (`none`, `sass`, `less`)。
- `--css-fw`: CSS 框架 (`none`, `unocss`, `tailwind`)。
- `--git` / `--no-git`: 是否自动初始化 Git 仓库。

### 交互模式向导
1. **项目名称**: (例如：`my-component-library`)
2. **项目类型**: (Library, Web Application)
3. **底层 JS 框架**: (Vanilla TS, Vue 3, React, Svelte, Solid)
4. **前端 UI 框架**: (列表会根据上一题的选择动态过滤并呈现)
4. **CSS 预处理器**: (None, Sass/SCSS, Less)
5. **CSS 框架**: (None, UnoCSS, TailwindCSS)
6. **初始化 Git**: (自动执行 `git init`)

生成完成后，只需进入项目目录，安装依赖，即可开始开发：

```bash
cd my-component-library
pnpm install
pnpm dev   # 启动本地可视化开发环境
pnpm build # 编译打包用于生产环境
```

## 支持自动集成的 UI 库

目前脚手架支持为以下框架自动集成对应的 UI 组件库：
- **Vue 3**: Element Plus, Ant Design Vue, Vant
- **React**: Ant Design, Material UI (@mui/material)
- **Svelte**: Sveltestrap
- **Solid**: SUID (@suid/material)

*(你当然也可以在选项中选择 "None" 来获取一个没有任何 UI 预设的纯净版模板)。*

## 本地开发指南

1. 克隆本仓库。
2. 运行 `pnpm install` 安装依赖。
3. 核心逻辑位于 `bin/index.js`，静态底座模板位于 `template/` 目录下。
4. 本脚手架源码仓库已配置 Husky + Commitlint 强制验证约定式提交规范。
5. 当你准备发布脚手架的新版本到 NPM 时，请确保登录了官方源（如果你本地全局使用了淘宝镜像或 CNPM），然后运行发版命令：
   ```bash
   npm login --registry=https://registry.npmjs.org/
   pnpm release
   ```
   （`release-it` 将全自动完成版本号升级、Git Tag 打标以及 NPM 发包）。

### 测试脚本执行说明

我们提供了几个自动化的测试脚本，这些脚本利用预设参数快速验证不同框架模板的生成是否正常，无需手动点选：

- `node test-cli.js` - 测试生成 React + Ant Design 项目。
- `node test-cli-vue.js` - 测试生成 Vue 3 + Element Plus 项目。
- `node test-cli-solid.js` - 测试生成 Solid + SUID 项目。

### 提交规范 (Commit Convention)

本项目使用 `commitlint` 强制推行 [Conventional Commits (约定式提交)](https://www.conventionalcommits.org/zh-hans/) 规范。
在提交代码时，你的 Commit Message 必须以特定的前缀开头，并且冒号后面需要有一个空格。常用的前缀包括：

- `feat: 新增某某功能` (新功能)
- `fix: 修复某某bug` (Bug 修复)
- `chore: 更新相关配置` (构建过程或辅助工具的变动)
- `docs: 更新文档说明` (文档修改)

如果不遵循此格式，Git Hook 会拦截并拒绝你的提交。

## 开源协议

[MIT](./LICENSE)