OpenParable
Skip to content
← Back to skills

New Hook

Development
new-hook

New Hook is an Agent Skill for development published in the childrentime/reactuse repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Scaffold a new React hook in @reactuses/core with the repo's real conventions (interface.ts + multilingual JSDoc, SSR-safe browser access, shared-util reuse, 3-part public export). Triggers on "add a hook", "new hook", "scaffold a hook", "create a useXxx", or when implementing a new piece of hook functionality in packages/core.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/childrentime/reactuse/blob/HEAD/.claude/skills/new-hook/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/new-hook, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.

⚠️ Do not run pnpm newHook. scripts/newHook.ts is stale — it writes to packages/core/hooks/ and packages/website/src/routes.json, neither of which exists anymore (hooks live in packages/core/src/). Do the steps below manually.

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
}

Step 2 — Wire it into the public API

Edit packages/core/src/index.ts — all three parts, or the hook/types won't ship:

import { useX } from './useX'        // 1. with the other imports

export {
  // …
  useX,                              // 2. inside the export { } block
}

export * from './useX/interface'    // 3. with the other `export *` lines

Conventions to follow

  • SSR-safety is mandatory. Guard any window/document/navigator access with defaultWindow / defaultDocument (../utils/browser) or isBrowser / isNavigator (../utils/is). For subscribed external state, use the use-sync-external-store/shim pattern with a server fallback (see useColorMode, useLocationSelector).
  • Reuse utilities — don't hand-roll addEventListener (use useEventListener), stale closures (useLatest), or unmount cleanup (useUnmount).
  • Return shape: a tuple with as const, or an explicitly typed object. Be consistent with the closest existing hook.
  • Dev-time validation of arguments behind if (isDev) { … console.error(…) }.
  • Stay on task — don't refactor neighbors or fix unrelated lint while you're here.

Step 3 — Then

  1. Tests → hook-test skill.
  2. Docs → hook-docs skill (+ bash scripts/generate-hook-registry.sh).
  3. Verify: pnpm --filter @reactuses/core test useX and pnpm lint.

Or run /new-hook <useName> "<description>" <category> to do the whole pipeline at once.