@repo/hooks - React Hooks 工具库

通用的 React Hooks 工具集合，支持国际化验证、错误处理、键盘快捷键等场景。

安装

Workspace 内使用

{
  "dependencies": {
    "@repo/hooks": "workspace:*"
  }
}

从 npmjs 使用

{
  "dependencies": {
    "@dofe/sso-hooks": "^0.1.0"
  }
}

包含的 Hooks

| Hook | 描述 | 依赖 | | ---------------------- | ------------------------------ | ------------------------ | | useDebouncedValue | 防抖值更新 | react | | useHotkeys | 键盘快捷键绑定 | react | | usePermissions | 权限管理 | react | | useAspectRatioSize | 宽高比尺寸计算 | react | | useOperationFeedback | 统一的操作反馈（toast） | react, sonner, next-intl | | useErrorHandler | 统一错误处理，自动分类显示 | react, sonner, next-intl | | useI18nValidation | 国际化表单验证 Zod Schema 生成 | react, zod, next-intl |

使用示例

useDebouncedValue

import { useDebouncedValue } from '@repo/hooks';

const [search, setSearch] = useState('');
const debouncedSearch = useDebouncedValue(search, 500);

// debouncedSearch 会在 500ms 后更新

useHotkeys

import { useHotkeys } from '@repo/hooks';

useHotkeys(
  'ctrl+s',
  (event) => {
    event.preventDefault();
    handleSave();
  },
  { scope: 'editor' },
);

useI18nValidation

import { useI18nValidation, createPasswordConfirmSchema } from '@repo/hooks';

const v = useI18nValidation();

// 使用预定义验证器
const schema = z.object({
  email: v.email(),
  phone: v.phone(),
  password: v.password({ min: 6, requireStrong: true }),
  username: v.required('username'),
  bio: v.string('description', { max: 200 }),
});

// 密码确认 schema
const passwordSchema = createPasswordConfirmSchema(v, {
  passwordField: 'password',
  confirmField: 'confirmPassword',
  minLength: 8,
});

useOperationFeedback

import { useOperationFeedback } from '@repo/hooks';

const { success, error, warning, info, loading, promise } = useOperationFeedback();

success('操作成功');
error('操作失败');

// Promise toast
const result = await promise(saveData(), {
  loading: '保存中...',
  success: '保存成功',
  error: '保存失败',
});

useErrorHandler

import { useErrorHandler, NetworkError, ValidationError } from '@repo/hooks';

const handleError = useErrorHandler();

try {
  await fetchData();
} catch (error) {
  if (!response.ok) {
    handleError(new NetworkError('网络错误'));
  } else {
    handleError(new ValidationError('验证失败'));
  }
}

目录结构

src/
├── useDebouncedValue.ts     # 防抖 hook
├── useHotkeys.ts            # 键盘快捷键 hook
├── usePermissions.ts        # 权限 hook
├── useAspectRatioSize.ts    # 宽高比尺寸 hook
├── useOperationFeedback.ts  # 操作反馈 hook
├── useErrorHandler.ts       # 错误处理 hook
├── useI18nValidation.ts     # 国际化验证 hook
└── index.ts                 # 导出汇总

构建

pnpm --filter @repo/hooks build

NPM 发布流程

发布说明

本包在 workspace 内使用名称 @repo/hooks，发布到 npmjs 时使用名称 @dofe/sso-hooks。

发布脚本会自动处理名称转换：

• prepack - 发布前将名称改为 @dofe/sso-hooks，移除 workspace 依赖
• postpack - 发布后恢复为 @repo/hooks，恢复 workspace 依赖

发布命令

从根目录发布（推荐）

# 在 sso.dofe.ai 根目录执行

# 发布单个包
pnpm release:hooks              # 发布 @dofe/sso-hooks
pnpm release:hooks:otp          # 带 OTP 发布

# 批量发布所有包
pnpm release:all                # 发布 contracts、hooks、ui
pnpm release:all:otp            # 带 OTP 批量发布

从包目录发布

# 进入 hooks 目录
cd sso.dofe.ai/packages/hooks

# 手动发布流程
pnpm build
node scripts/prepack.mjs
npm publish --access public --ignore-scripts --otp=<你的OTP码>
node scripts/postpack.mjs

从根目录发布流程详解

pnpm release:hooks:otp

执行步骤：

1. 进入 packages/hooks 目录
2. 运行 prepack 修改 package.json（名称、移除 workspace 依赖）
3. 执行 npm publish --access public --ignore-scripts --otp
4. 运行 postpack 恢复 package.json 原始状态

前置条件

1. npm 账户登录：

   npm login

2. 验证登录状态：

   npm whoami

3. 确保有 @dofe organization 的发布权限

Peer Dependencies

使用此包的项目需要安装以下依赖：

{
  "dependencies": {
    "next-intl": "^4.0.0",
    "react": "^19.0.0",
    "sonner": "^2.0.0",
    "zod": "^3.24.0"
  }
}

常见问题

发布失败 "Cannot resolve @repo/constants"

确保运行了 prepack 脚本，它会移除 workspace 依赖。

本地安装失败 "Cannot resolve @repo/hooks"

这是因为 workspace 依赖问题。确保在 sso.dofe.ai 项目根目录运行 pnpm install。