| name | tsh-writing-hooks |
| description | Custom hook and composable patterns — naming, composition, stable return shapes, lifecycle cleanup, and testing strategies. Use when writing reusable logic units (React hooks, Vue composables), refactoring logic into hooks, debugging hook behavior, or reviewing hook implementations. |
| user-invocable | false |
Writing Hooks
Provides patterns for writing composable, testable custom hooks with stable APIs, proper effect lifecycle management, and clear responsibility boundaries.
This skill uses "hook" to refer to any reusable, composable logic unit — React hooks, Vue composables, or equivalent framework abstractions. Adapt naming conventions and specific APIs to the project's framework.
Each hook does one thing. Compose complex behavior by calling multiple hooks, not by adding optional parameters to a single hook. A hook with 5+ configuration options is a sign it needs decomposition.
Prefer returning an object (rather than a tuple) once the hook returns more than 1–2 values, and keep references stable. Memoize callbacks and derived values using the framework's memoization primitives when consumers may pass them to memoized children. The hook's return shape is its public API — treat it as a contract.
Every subscription, timer, event listener, or async operation created in an effect must have a corresponding cleanup. Leaked resources cause memory leaks and stale state bugs that are hard to diagnose.
Hook Development Process
Use the checklist below and track progress:
Progress:
- [ ] Step 1: Define the hook's contract
- [ ] Step 2: Classify the hook tier
- [ ] Step 3: Implement with lifecycle discipline
- [ ] Step 4: Test the hook
Step 1: Define the hook's contract
Define the hook's public API before writing implementation code.
Naming: Follow the project's framework convention for reusable logic units. In React and Vue, the convention is use prefix + descriptive verb or noun. The name reflects behavior, not implementation details.
| Pattern | Example | Use case |
|---|
use + noun | useDebounce, useMediaQuery | Returns a derived or observed value |
use + verb | useToggle, useFetch | Returns value + action(s) |
use + domain | useAuth, useCart | Domain-specific composition hook |
Good: useLocalStorage — describes what it does.
Bad: useBrowserEffect — describes how it works.
Inputs: Prefer a single options object when the hook accepts 3+ parameters. This makes the API extensible without breaking existing call sites.
const useDebounce = ({ value, delay, leading }: UseDebounceOptions) => {
};
const useDebounce = (value: string, delay: number, leading?: boolean) => {
};
Outputs: Return an object with clear field names. Document what the hook returns and when it triggers effects.
interface UseAsyncReturn<T> {
data: T | undefined;
error: Error | null;
isPending: boolean;
refetch: () => void;
}
Step 2: Classify the hook tier
Determine where the hook fits in the dependency hierarchy. This classification constrains what a hook may depend on and prevents circular or inappropriate coupling.
| Tier | Name | Scope | Dependencies | Examples |
|---|
| Atom | UI hooks | Local state, DOM events, media queries, keyboard | No remote data. No data-fetching libraries. | useToggle, useMediaQuery, useKeyPress |
| Molecule | Coordination hooks | Compose atom hooks with light coordination logic | Other atom hooks only. No remote data. | useFormField, usePagination |
| Organism | Data hooks | Wrap data-fetching/mutation libraries. Domain logic. | May call UI hooks internally. Interact with server cache. | useUserProfile, useSearchResults |
Rules:
- Atom hooks must never import data-fetching or state management libraries.
- Molecule hooks compose atoms — they do not call data hooks.
- Organism hooks may call any tier but are the only tier that touches remote data.
Composability example — molecule hook composing atoms:
const useDebounce = (value: string, delay: number) => {
};
const useLocalStorage = <T>(key: string, initial: T) => {
};
const useDebouncedSearch = (storageKey: string) => {
const { value, setValue } = useLocalStorage(storageKey, "");
const debouncedValue = useDebounce(value, 300);
return { query: value, setQuery: setValue, debouncedQuery: debouncedValue };
};
Step 3: Implement with lifecycle discipline
Follow these rules during implementation:
Call rules:
- Call hooks/composables at the top level only — never inside conditions, loops, or nested functions.
- Ensure all reactive dependencies are properly tracked — whether through explicit dependency arrays or automatic reactivity tracking, depending on the framework. Suppressing framework lint rules for dependency tracking is a last resort, not a shortcut.
- Avoid object or array literals in dependency declarations — they create new identities every render/update cycle. Lift constants to module scope or memoize them.
Lifecycle cleanup — every effect that creates a resource must clean it up:
| Resource | Setup | Required cleanup |
|---|
| Timer | setTimeout(cb, delay) | clearTimeout(id) |
| Event listener | addEventListener(event, handler) | removeEventListener(event, handler) |
| Async operation | Cancellable operation with AbortController signal | controller.abort() |
| Subscription | source.subscribe(handler) | subscription.unsubscribe() |
The cleanup must execute when the hook unmounts or when dependencies change. See the framework reference for the exact cleanup syntax.
Error handling:
- Don’t throw for expected runtime errors from the render/setup phase — surface those via the return value (
{ error }).
- It is acceptable to throw during render/setup for programmer errors (for example, a
useX hook used outside its Provider) or when integrating with Error Boundaries / Suspense.
- Catch async errors inside effects and store them in state.
Conditional execution:
- Data hooks should support an
enabled flag to prevent wasteful operations when preconditions are not met.
const useUserProfile = ({ userId, enabled = true }: Options) => {
};
Step 4: Test the hook
Use the framework's hook/composable testing utility. Structure tests around four areas:
- Initial state — Verify the hook returns the expected default values on first render.
- State transitions — Trigger actions and assert the return value updates correctly.
- Effect cleanup — Unmount the hook and verify all resources are released (timers cleared, listeners removed, subscriptions cancelled).
- Error states — Simulate failures and verify the hook surfaces errors via its return value.
For data hooks: wrap the test in required providers (query client, context providers) and mock network responses.
For timer-dependent hooks: use fake timers to control time progression without real delays.
it("cleans up the timer on unmount", () => {
});
Return Shape Guidelines
| Return type | When | Example |
|---|
| Single value | Hook computes one thing | useDebounce(value, delay) → debouncedValue |
| Object | Multiple related values or actions | { data, error, isPending, refetch } |
| Object (prefer over tuple) | Readability and evolvability matter | { count, increment, decrement, reset } |
Prefer objects over tuples for hooks returning more than one value. Objects are self-documenting, allow consumers to destructure only what they need, and evolve without breaking existing call sites.
Anti-Patterns
| Anti-Pattern | Instead Do |
|---|
Tuple return [value, setter] for complex hooks | Object return { value, setValue, reset } |
| Effect with suppressed dependency tracking | Include all deps; restructure if cycle occurs |
| New object/array identity every render | Memoize or lift to module scope |
| Side effects in render phase | Move to lifecycle effect or event handler |
| Swallowing errors silently | Return { error } so consumer can handle |
| One mega-hook with 10 options | Compose from smaller single-purpose hooks |
| Timer without cleanup | Always return () => clearTimeout(id) |
Data hook without enabled flag | Support conditional fetching to avoid waste |
Hook Quality Checklist
Hook:
- [ ] Name follows framework convention (e.g., `use` prefix), describes behavior (not implementation)
- [ ] Single responsibility — does one thing well
- [ ] Inputs: single options object for 3+ params
- [ ] Output: object with stable references (memoized where framework supports it)
- [ ] All dependency tracking complete — no linting suppression
- [ ] Effects clean up: timers, listeners, subscriptions, abort controllers
- [ ] Errors surfaced via return value, never thrown from render
- [ ] Tested: initial state, transitions, cleanup, error states
Framework-Specific Patterns
The patterns above are framework-agnostic. For framework-specific hook/composable syntax, load the appropriate reference:
- React: See
./references/react-patterns.md — useEffect, useMemo, useCallback, dependency arrays, rules of hooks.
Connected Skills
tsh-implementing-frontend — hooks are used within components; this skill covers component patterns
tsh-optimizing-frontend — for memoization strategies and performance patterns in hooks
tsh-reviewing-frontend — for hook-specific code review criteria
tsh-implementing-forms — for form-related custom hooks (field state, validation triggers)