@fix-the-world/utils

通用前端工具包：请求封装、校验、工具方法、Pinia stores、Vue 登录组件，以及 ESLint / Vite / Umi 预设。

维护者 / Agent 请先阅读 AGENTS.md。

子路径导出

| 子路径 | 用途 | |--------|------| | @fix-the-world/utils | 主入口：utils、request、config、hooks、stores、reg、validators、formatters、init | | @fix-the-world/utils/vite | Vite autoImport 预设（供业务项目使用） | | @fix-the-world/utils/umi | Umi / Webpack autoImport 预设 | | @fix-the-world/utils/eslint | 统一 ESLint flat config | | @fix-the-world/utils/qiankun | 微前端 qiankun 封装 | | @fix-the-world/utils/vue/* | Vue 组件（.vue 源码），如 vue/login-code | | @fix-the-world/utils/vue/*/types | 对应组件类型 | | @fix-the-world/utils/vue/*/services | 对应组件 services | | @fix-the-world/utils/types/main | GRes、GRecords 等全局接口类型 | | @fix-the-world/utils/types/global | auto-import 全局类型（业务项目启用 auto-import 时使用） |

0.5.0 起已移除 SCSS / BEM，样式由业务项目自行配置。

安装

必需 peer：

pnpm i @fix-the-world/utils axios crypto-js json-bigint vue pinia valtio

按需安装（安装后会通过 postinstall 提示缺失项）：

| 能力 | 依赖 | |------|------| | ESLint 预设 | @antfu/eslint-config eslint eslint-plugin-format eslint-plugin-vue | | Vite auto-import | vite unplugin-auto-import | | Vue 登录组件 | element-plus | | Umi 预设 | @umijs/max | | qiankun | qiankun vite-plugin-qiankun | | 路由 hooks | vue-router |

初始化

import { init, request } from '@fix-the-world/utils'
import { ElLoading } from 'element-plus'

init({
  storage: { prefix: 'my-app' },
  user: {
    api: () => fetch('/api/user').then(r => r.json()),
  },
  login: {
    codeSendInterval: 60,
    codeSendSaveKey: 'code-send-time',
  },
})

request.setConfig({
  baseURL: '/api',
  loading: {
    creator: () => ElLoading.service({ lock: true, text: '加载中' }),
  },
})

• config：全局配置（valtio），不依赖 Pinia
• request：默认 loading: false，需自行传入 Element Plus ElLoading
• stores.useStoreUser()：用户信息 store，依赖 config.user.api
• hooks.useSendCode()：验证码倒计时，依赖 config.login

Vue 登录组件

组件以 .vue 源码 发布，由业务项目 Vite 编译。组件内已写显式 import，不依赖 auto-import。

<script setup lang="ts">
import FtwLoginCode from '@fix-the-world/utils/vue/login-code'
import type { ILoginCode } from '@fix-the-world/utils/vue/login-code/types'
import { ref } from 'vue'

const model = ref<ILoginCode>({ account: '', code: '' })
</script>

<template>
  <FtwLoginCode
    v-model="model"
    :apis="{ send: () => Promise.resolve(), login: () => Promise.resolve({}) }"
  />
</template>

业务项目需安装 element-plus，并配置 @vitejs/plugin-vue。

主入口（显式导入）

import {
  ApiRequest,
  config,
  formatters,
  hooks,
  init,
  objectDefaults,
  reg,
  request,
  stores,
  utils,
  validators,
} from '@fix-the-world/utils'
import type { IConfig, IRequestConfig } from '@fix-the-world/utils'

详见 request 示例。

Vite auto-import（业务项目可选）

import hzwVite from '@fix-the-world/utils/vite'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    hzwVite.autoImport({
      dts: './src/types/auto-imports.d.ts',
    }),
  ],
})

预设自动导入：vue、pinia、vue-router、element-plus 部分 API、@fix-the-world/utils 主入口导出。
dirs 默认为 []，扫描业务项目目录需自行传入。

ESLint

import eslint from '@fix-the-world/utils/eslint'

export default eslint()

TypeScript

{
  "compilerOptions": {
    "types": [
      "@fix-the-world/utils/types/main",
      "@fix-the-world/utils/types/global"
    ]
  }
}

纯显式导入可省略 types/global。

本地联调

# 本仓库
pnpm i && pnpm start        # 开发预览 http://localhost:9999
pnpm build                  # 构建 dist

# 业务项目引用本地包
pnpm link --global          # 在本仓库执行
pnpm link --global @fix-the-world/utils  # 在业务项目执行

# 或 package.json
"@fix-the-world/utils": "file:../utils"

修改后需重新 pnpm build，业务项目才能拿到最新 dist。

开发脚本

| 命令 | 说明 | |------|------| | pnpm start | 本地 dev（src/dev 预览页） | | pnpm build | 清理 → 打包 → 生成类型 | | pnpm lint | ESLint 检查 vue 组件 | | pnpm rules | ESLint 规则可视化（9090 端口） | | pnpm release | build + npm publish |