Tsh Writing Hooks

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.

<principles>

<single-responsibility>
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.
</single-responsibility>

<stable-api-surface>
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.
</stable-api-surface>

<cleanup-everything>
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.
</cleanup-everything>

</principles>

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.

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.

// Prefer — single options object
const useDebounce = ({ value, delay, leading }: UseDebounceOptions) => {
  // ...
};

// Avoid — positional args are fragile past 2 params
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.

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:

// Atom: single-purpose, no data fetching
const useDebounce = (value: string, delay: number) => {
  /* ... */
};
const useLocalStorage = <T>(key: string, initial: T) => {
  /* ... */
};

// Molecule: composes atoms into a higher-level behavior
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:

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.