# zl-loom

**Repository Path**: wanglaibin/zl-loom

## Basic Information

- **Project Name**: zl-loom
- **Description**: A CLI tool for building Vue projects with rsbuild and vite
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zl-tools

统一构建 CLI：一套命令同时支持 **Vite** 和 **Rsbuild** 引擎，并内置
lint / format / commit 工具链。

## 特性

- 🔧 **引擎无关**：`-e vite` / `-e rsbuild` 一行切换，其余命令完全一致
- 📦 **零额外依赖**：oxlint / oxfmt / commitlint / czg / husky / lint-staged 全部内置
- 🔌 **插件化**：内置 Vue 支持、Chunk 分包、包体积分析，可按需禁用或覆盖
- 🧩 **配置探测**：自动识别 Vite 项目结构（`index.html` + `src/main.ts`）和 Rsbuild 项目结构

## 安装

```bash
pnpm add -D zl-tools
```

按需安装引擎（至少要装一个）：

```bash
# 使用 Vite 引擎
pnpm add -D vite @vitejs/plugin-vue

# 使用 Rsbuild 引擎
pnpm add -D @rsbuild/core @rsbuild/plugin-vue
```

## 快速开始

```bash
# 写入默认配置 + 安装 git hooks
npx zl-tools setup

# 开发 / 构建 / 预览
npx zl-tools dev
npx zl-tools build
npx zl-tools preview

# 切换引擎
npx zl-tools dev -e rsbuild
npx zl-tools build -e rsbuild
```

## 命令

| 命令 | 说明 |
|---|---|
| `zl-tools dev` | 启动开发服务器 |
| `zl-tools build` | 生产构建 |
| `zl-tools preview` | 预览构建产物 |
| `zl-tools lint [files...]` | oxlint 校验，`--fix` 自动修复 |
| `zl-tools format [files...]` | oxfmt 格式化，`--check` 只检查 |
| `zl-tools commit` | 交互式生成 Conventional Commits 信息 |
| `zl-tools commitlint` | 校验提交信息（供 hook 调用） |
| `zl-tools lint-staged` | 对 staged 文件运行 lint / format（供 hook 调用） |
| `zl-tools setup` | 一键写入配置 + 安装 hooks |

## 用户配置：`app.config.ts`

CLI 启动时自动加载项目根目录下的 `app.config.ts` / `.mts` / `.mjs` / `.js`。
用 `satisfies` 指定引擎配置类型即可获得完整类型提示：

```ts
import type { ViteUserConfig } from 'zl-tools/engines/vite'

export default {
  envPrefix: 'PUBLIC_',           // 引擎无关
  engine: {                        // 透传给 Vite / Rsbuild 的原生配置
    resolve: { alias: { '@': '/src' } },
  },
  plugins: [],                     // 用户插件，同名时覆盖内置
  disableBuiltinPlugins: [],       // 例如 ['vite:chunk-split']
  bundleAnalyzer: true,            // 或 { enabled: true, provider: 'visualizer' }
} satisfies ViteUserConfig
```

Rsbuild 引擎同理：

```ts
import type { RsbuildUserConfig } from 'zl-tools/engines/rsbuild'
```

## 与纯 Vite 的差异

- **环境变量前缀默认是 `PUBLIC_`**，不是 `VITE_`。如需保持兼容，
  在 `app.config.ts` 里设置 `envPrefix: 'VITE_'`。
- **内置插件**：Vue、chunk-split 默认注入，可在 `disableBuiltinPlugins` 里关闭。
- **chunk-split**：Vite 侧走 Rolldown `codeSplitting`（Vite 8 API），
  Rsbuild 侧走 `performance.chunkSplit`。用户显式配置时不覆盖。

## 内置工具链

`zl-tools setup` 会写入以下文件（已存在时跳过，`--force` 覆盖）：

| 文件 | 用途 |
|---|---|
| `.oxlintrc.json` | lint 规则（Vue 逻辑规则开，格式规则关） |
| `.oxfmtrc.json` | format 规则（Prettier 兼容） |
| `commitlint.config.mjs` | 提交信息规则（自包含，无需 extends） |
| `.czrc` | 交互式提交配置 |
| `lint-staged.config.mjs` | staged 文件的 lint / format 流程 |

## 移除工具链

```bash
# 只移除 zl-tools 写入的 hooks（保留用户自定义部分）
npx zl-tools setup --remove-hooks

# 移除配置文件需要手动删除
rm .oxlintrc.json .oxfmtrc.json commitlint.config.mjs .czrc lint-staged.config.mjs
```

## 环境要求

- Node `>=20.19.0`
- Vite 引擎需要 `vite >= 8`
- Rsbuild 引擎需要 `@rsbuild/core >= 2`