new-hook

new-hook — scaffold a hook the ReactUse way

Use this when adding a new hook to @reactuses/core. It encodes how hooks are actually built in this repo today. Pair it with hook-test and hook-docs afterward.

There is no scaffolding script — hooks are created by hand. Follow the steps below.

Step 0 — Understand before writing (don't skip)

1. Confirm the hook doesn't already exist: ls packages/core/src/useX.
2. Read 1-2 similar existing hooks end to end (not just their names) to match style — e.g. a state hook like useCounter, a browser hook like useClipboard, an element hook like useEventListener. Note their return shape and which utils they reuse.
3. Check the knowledge base reuse cheat-sheet — much of what you need (useLatest, useUnmount, useEventListener, defaultWindow, isBrowser) is already written. Reuse before writing.

Step 1 — Create the hook folder

packages/core/src/useX/ with two (then three) files:

• index.ts — the implementation, named export export const useX: UseX = ….
• interface.ts — the public type UseX with multilingual JSDoc.
• index.spec.ts — tests (hand off to the hook-test skill).

interface.ts template

Types live here (not inline), so the API-doc generator can read them. JSDoc is trilingual:

/**
 * @title useX
 * @returns_en What the hook returns, described for docs.
 * @returns 返回值说明（简体）。
 * @returns_zh-Hant 返回值說明（繁體）。
 */
export type UseX = (
  /**
   * @en The first argument, described.
   * @zh 第一个参数说明。
   * @zh-Hant 第一個參數說明。
   * @defaultValue 0
   */
  initial?: number,
) => readonly [number, (n: number) => void]

(See packages/core/src/useCounter/interface.ts for a full real example.)

index.ts template

import { useState, useCallback } from 'react'
import { isDev, isFunction } from '../utils/is'
import type { UseX } from './interface'

export const useX: UseX = (initial = 0) => {
  if (isDev && initial != null && !isFunction(initial) && typeof initial !== 'number') {
    console.error(`useX: \`initial\` expected number, got "${typeof initial}".`)
  }

  const [value, setValue] = useState(initial)
  const set = useCallback((n: number) => setValue(n), [])

  return [value, set] as const
}