Hooks

Custom hooks live next to the feature they serve. Cross-feature hooks live in src/lib/hooks/. Naming is use-<concept>.ts, kebab-case.

Categories

Rules

Canonical example

Copy"use client"
 
import { useState, useTransition } from "react"
 
import { deleteSubject } from "./actions"
 
export function useSubjectActions() {
  const [pending, startTransition] = useTransition()
  const [error, setError] = useState<string | null>(null)
 
  function remove(id: string, onSuccess?: () => void) {
    startTransition(async () => {
      const res = await deleteSubject({ id })
      if (res.success) {
        onSuccess?.()
      } else {
        setError(res.errorCode)
      }
    })
  }
 
  return { remove, pending, error }
}

Shared hooks already lifted

These live in src/lib/hooks/ — don't reinvent.

Anti-patterns

• use-media-query duplicated 5 times, use-callback-ref 3×, use-mobile 3× — lift to src/lib/hooks/.
• Multi-hook files — form/use-form.ts is 523 lines exporting 5 hooks. Split.
• Returning tuples ([value, setValue, loading]) — switch to objects.
• Side effects in render — wrap in useEffect or useTransition.
• Reading window without an SSR guard — use typeof window !== "undefined" or useSyncExternalStore.

Naming

• File: use-<concept>.ts (kebab-case).
• Function: use<Concept> (camelCase, use prefix).
• Cross-feature: src/lib/hooks/use-<concept>.ts.
• Single-purpose — resist exporting 5 hooks per file.

Sibling roles

• Hooks consume server actions from actions.ts.
• Hooks don't import db directly — server-only.
• Hooks export to client.tsx, form.tsx, table.tsx. Server components don't use them.

See also

• Pattern
• Actions
• Util
• Content