r-utils

前端工具库 monorepo，使用 pnpm workspace + Turbo 管理任务，Vite 构建。

包列表

包名	路径	描述
@r-utils/common	packages/common	通用 JS/TS 工具（权限、倒计时、打印、时间等）
@r-utils/vue3	packages/vue3	Vue3 工具（class 处理、dispatch 等）
@r-utils/uni-app	packages/uni-app	uni-app 工具（请求封装、蓝牙、NFC、打印、Vue3 Hooks 等）
@r-utils/uview-plus	packages/uview-plus	uview-plus 组合式 API Hooks（Picker、Calendar 等）
@r-utils/vue2	packages/vue2	Vue2 工具（visibility 插件）

环境要求

• Node.js >= 18.12.0
• pnpm >= 10.0.0

安装依赖

pnpm install

构建

构建所有包

pnpm build

Turbo 会自动按依赖拓扑排序构建（例如 @r-utils/common 会先于依赖它的包构建），并复用缓存加速重复任务。

构建单个包（Turbo 过滤）

pnpm build -- --filter=@r-utils/common

构建单个包

cd packages/common
pnpm build

每个包使用 Vite lib 模式构建，输出到 dist/ 目录：

dist/
├── index.mjs       # ESM 格式
├── index.cjs       # CJS 格式
├── index.d.ts      # TypeScript 类型声明
├── index.mjs.map   # Source Map
└── index.cjs.map

监听模式

# 监听所有包
pnpm build:watch

# 仅监听单个包
pnpm build:watch -- --filter=@r-utils/common

使用方式

ESM 引入（推荐）

支持 tree-shaking，打包工具会自动按需引入用到的部分。

// 完整引入
import { Permission, Countdown, KnockTest } from '@r-utils/common';

// 按需引入（bundler 自动 tree-shaking，只打包 Permission）
import { Permission } from '@r-utils/common';

// Vue3 工具
import { mergeClass, dispatch } from '@r-utils/vue3';

// uni-app 工具
import { Request } from '@r-utils/uni-app';

// uni-app Vue3 Hooks
import { useShare } from '@r-utils/uni-app/vue3';

// uview-plus Hooks
import { usePickerSingle, usePicker, useCalendar } from '@r-utils/uview-plus';

// Vue2 插件
import { VisibilityPlugin } from '@r-utils/vue2';
Vue.use(VisibilityPlugin);

CJS 引入

const { Permission } = require('@r-utils/common');

package.json exports

每个包均配置了标准的 exports 字段，打包工具会自动选择正确的格式：

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

开发

测试

# 运行所有测试
pnpm test

# 运行单个测试文件
pnpm vitest run packages/common/test/permission.test.ts

代码检查与格式化

pnpm lint
pnpm format

Git 提交

项目使用 Conventional Commits 规范,通过 commitizen + cz-git 提供交互式提交体验。

# 使用交互式提交(推荐)
pnpm commit

提交时 husky 会自动运行:

• lint-staged - 代码检查和格式化
• pnpm test（Vitest） - 单元测试
• commitlint - 提交信息格式校验

详细说明请参考 提交规范指南。

发布

发布流程已提取到独立文档：发布流程。

常用命令：

pnpm changeset        # 记录变更
pnpm release:check    # 测试 + 构建
pnpm release          # 更新版本号与 CHANGELOG
pnpm release:publish  # 发布到 npm 仓库
pnpm release:all      # 一键执行检查 + 版本更新 + 发布

项目已配置发布到私有 npm 仓库 http://npm.nps.yunvip123.cn。

安装已发布的包

# 配置 npm registry
npm config set registry http://npm.nps.yunvip123.cn

# 或在项目中使用 .npmrc 文件
echo "registry=http://npm.nps.yunvip123.cn" > .npmrc

# 安装包
pnpm add @r-utils/common
pnpm add @r-utils/vue3
pnpm add @r-utils/uni-app
pnpm add @r-utils/uview-plus
pnpm add @r-utils/vue2

项目结构

r-util-js/
├── packages/
│   ├── common/          # @r-utils/common
│   │   ├── src/
│   │   │   ├── permission/   # Permission 权限校验
│   │   │   ├── timer/        # Countdown、TimeoutTimer
│   │   │   ├── printer/      # ESC/TSC 打印指令
│   │   │   ├── knock-test/   # KnockTest 敲击触发
│   │   │   └── time/         # 时间工具
│   │   ├── vite.config.ts
│   │   └── tsconfig.json
│   ├── vue3/            # @r-utils/vue3
│   ├── uni-app/         # @r-utils/uni-app
│   ├── uview-plus/      # @r-utils/uview-plus
│   └── vue2/            # @r-utils/vue2
├── eslint.config.js     # ESLint v9 flat config
├── prettier.config.js
└── pnpm-workspace.yaml

参与贡献

欢迎贡献代码!请先阅读:

• 贡献指南 - 了解开发流程和规范
• 提交规范指南 - 了解 Git 提交规范

基本流程:

1. Fork 本仓库
2. 新建分支 feat/xxx 或 fix/xxx
3. 提交代码(使用 pnpm commit)
4. 新建 Pull Request