Skill de Criação de Hooks Personalizados - Uma receita Claude Code para criar hooks React reutilizáveis e bem testados

Q: Quando você deve extrair lógica para um hook personalizado em vez de mantê-la no componente?

Extraia quando o mesmo padrão useState + useEffect aparece em 2+ componentes. Extraia quando a lógica de estado complexa obscurece a lógica de renderização. Não extraia se a lógica for usada em um componente e for simples, ou se envolver um único useState.

Q: Como você torna um hook personalizado seguro para SSR?

Verifique typeof window !== "undefined" antes de acessar APIs do navegador como localStorage, navigator ou matchMedia. Retorne um padrão sensato durante o SSR (por exemplo, false para useMediaQuery).

Q: Por que as funções retornadas de hooks devem ser envolvidas em useCallback?

Sem useCallback, a referência da função muda a cada renderização. Componentes filhos que recebem a função como prop serão re-renderizados desnecessariamente. Referências estáveis evitam re-renderizações em cascata.

Q: Gotcha: Qual é a diferença entre useState(fn) e useState(fn())?

useState(() => expensiveComputation()) executa a função apenas uma vez na renderização inicial (inicializador preguiçoso). useState(expensiveComputation()) executa a função em cada renderização, desperdiçando computação.

Q: Qual é o padrão useRef para evitar closures obsoletas em useEffect?

Armazene o callback mais recente em um ref: handlerRef.current = handler. No efeito, chame handlerRef.current(...) em vez de handler(...). Isso permite que o closure do efeito permaneça estável (dependências vazias), enquanto sempre chama a função mais recente.

Estas receitas de skill são projetadas para Claude Code, mas também funcionam com outros agentes de codificação de IA que suportam arquivos de skill/instrução.

Receita

O conteúdo completo do SKILL.md que você pode copiar para .claude/skills/custom-hooks-crafting/SKILL.md:

---
name: custom-hooks-crafting
description: "Criação de hooks React personalizados e reutilizáveis com TypeScript adequado. Use quando solicitado para: criar um hook, hook personalizado, extrair hook, hook reutilizável, composição de hooks, testar um hook."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Criação de Hooks Personalizados
 
Você é um especialista em criar hooks React personalizados. Cada hook que você cria segue princípios de design rigorosos, é totalmente tipado, seguro para SSR e testável.
 
## Regras de Design de Hooks
 
1. **Responsabilidade única** - Cada hook faz exatamente uma coisa.
2. **Nome começa com `use`** - Sempre prefixe com `use` (o React impõe isso).
3. **Convenções de tipo de retorno:**
   - Valor único: retorne o valor diretamente.
   - Valor + setter: retorne uma tupla `[valor, setter]` (como useState).
   - Múltiplos valores relacionados: retorne um objeto `{ valor, loading, error }`.
4. **Aceite configuração como um objeto** - Quando um hook recebe mais de 2 parâmetros, use um objeto de opções.
5. **Forneça padrões sensatos** - Cada opção deve ter um valor padrão.
6. **Limpe após você mesmo** - Sempre retorne funções de limpeza de useEffect.
7. **Segurança SSR** - Verifique `typeof window !== "undefined"` antes de acessar APIs do navegador.
8. **Referências estáveis** - Envolva funções retornadas em useCallback, envolva objetos retornados em useMemo.
 
## Template de Criação de Hook
 
```tsx
import \{ useState, useEffect, useCallback, useRef \} from "react";
 
interface UseMyHookOptions \{
  /** Descrição da opção */
  enabled?: boolean;
  /** Descrição da opção */
  interval?: number;
\}
 
interface UseMyHookReturn \{
  /** Descrição do valor de retorno */
  data: string | null;
  /** Descrição do valor de retorno */
  loading: boolean;
  /** Descrição do valor de retorno */
  error: Error | null;
  /** Descrição do valor de retorno */
  reset: () => void;
\}
 
/**
 * Descrição do que o hook faz e quando usá-lo.
 *
 * @example
 * const \{ data, loading, error \} = useMyHook(\{ enabled: true \});
 */
export function useMyHook(options: UseMyHookOptions = \{\}): UseMyHookReturn \{
  const \{ enabled = true, interval = 1000 \} = options;
 
  const [data, setData] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
 
  // Use ref para valores necessários em efeitos, mas que não devem disparar re-execuções
  const intervalRef = useRef(interval);
  intervalRef.current = interval;
 
  useEffect(() => \{
    if (!enabled) return;
 
    let cancelled = false;
    setLoading(true);
 
    async function fetchData() \{
      try \{
        const result = await someAsyncOperation();
        if (!cancelled) \{
          setData(result);
          setLoading(false);
        \}
      \} catch (err) \{
        if (!cancelled) \{
          setError(err instanceof Error ? err : new Error(String(err)));
          setLoading(false);
        \}
      \}
    \}
 
    fetchData();
    return () => \{ cancelled = true; \};
  \}, [enabled]);
 
  const reset = useCallback(() => \{
    setData(null);
    setLoading(false);
    setError(null);
  \}, []);
 
  return \{ data, loading, error, reset \};
\}

Receitas Comuns de Hooks

useDebounce

export function useDebounce<T>(value: T, delay: number): T \{
  const [debouncedValue, setDebouncedValue] = useState(value);
 
  useEffect(() => \{
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  \}, [value, delay]);
 
  return debouncedValue;
\}

useMediaQuery

export function useMediaQuery(query: string): boolean \{
  const [matches, setMatches] = useState(false);
 
  useEffect(() => \{
    if (typeof window === "undefined") return;
 
    const media = window.matchMedia(query);
    setMatches(media.matches);
 
    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
    media.addEventListener("change", listener);
    return () => media.removeEventListener("change", listener);
  \}, [query]);
 
  return matches;
\}

useClickOutside

export function useClickOutside<T extends HTMLElement>(
  handler: () => void
): React.RefObject<T | null> \{
  const ref = useRef<T | null>(null);
 
  useEffect(() => \{
    const listener = (event: MouseEvent | TouchEvent) => \{
      if (!ref.current || ref.current.contains(event.target as Node)) return;
      handler();
    \};
 
    document.addEventListener("mousedown", listener);
    document.addEventListener("touchstart", listener);
    return () => \{
      document.removeEventListener("mousedown", listener);
      document.removeEventListener("touchstart", listener);
    \};
  \}, [handler]);
 
  return ref;
\}

useLocalStorage

export function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void] \{
  const [storedValue, setStoredValue] = useState<T>(() => \{
    if (typeof window === "undefined") return initialValue;
    try \{
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    \} catch \{
      return initialValue;
    \}
  \});
 
  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => \{
      setStoredValue((prev) => \{
        const next = value instanceof Function ? value(prev) : value;
        if (typeof window !== "undefined") \{
          window.localStorage.setItem(key, JSON.stringify(next));
        \}
        return next;
      \});
    \},
    [key]
  );
 
  return [storedValue, setValue];
\}

useIntersectionObserver

interface UseIntersectionOptions \{
  threshold?: number;
  rootMargin?: string;
  triggerOnce?: boolean;
\}
 
export function useIntersectionObserver<T extends HTMLElement>(
  options: UseIntersectionOptions = \{\}
): [React.RefObject<T | null>, boolean] \{
  const \{ threshold = 0, rootMargin = "0px", triggerOnce = false \} = options;
  const ref = useRef<T | null>(null);
  const [isVisible, setIsVisible] = useState(false);
 
  useEffect(() => \{
    const element = ref.current;
    if (!element || typeof IntersectionObserver === "undefined") return;
 
    const observer = new IntersectionObserver(
      ([entry]) => \{
        setIsVisible(entry.isIntersecting);
        if (entry.isIntersecting && triggerOnce) \{
          observer.unobserve(element);
        \}
      \},
      \{ threshold, rootMargin \}
    );
 
    observer.observe(element);
    return () => observer.disconnect();
  \}, [threshold, rootMargin, triggerOnce]);
 
  return [ref, isVisible];
\}

usePrevious

export function usePrevious<T>(value: T): T | undefined \{
  const ref = useRef<T | undefined>(undefined);
 
  useEffect(() => \{
    ref.current = value;
  \});
 
  return ref.current;
\}

Quando Extrair um Hook

Extraia um hook personalizado quando:

O mesmo padrão useState + useEffect aparece em 2+ componentes.
Um componente tem lógica de estado complexa que obscurece a lógica de renderização.
Você precisa compartilhar comportamento (não UI) entre componentes.
Testar a lógica independentemente do componente seria valioso.

NÃO extraia um hook quando:

A lógica é usada em apenas um componente e é simples.
Você está apenas envolvendo um único useState (adiciona indireção sem benefício).
O "hook" não usa nenhum hook do React internamente (faça uma função simples).

Template de Teste

import \{ renderHook, act, waitFor \} from "@testing-library/react";
import \{ useMyHook \} from "./useMyHook";
 
describe("useMyHook", () => \{
  it("retorna o estado inicial", () => \{
    const \{ result \} = renderHook(() => useMyHook());
    expect(result.current.data).toBeNull();
    expect(result.current.loading).toBe(false);
    expect(result.current.error).toBeNull();
  \});
 
  it("atualiza o estado na ação", () => \{
    const \{ result \} = renderHook(() => useMyHook(\{ enabled: true \}));
    act(() => \{
      result.current.reset();
    \});
    expect(result.current.data).toBeNull();
  \});
 
  it("lida com operações assíncronas", async () => \{
    const \{ result \} = renderHook(() => useMyHook(\{ enabled: true \}));
    await waitFor(() => \{
      expect(result.current.loading).toBe(false);
    \});
    expect(result.current.data).toBeDefined();
  \});
 
  it("limpa na desmontagem", () => \{
    const \{ unmount \} = renderHook(() => useMyHook());
    // Verifica se não há erros ou avisos na desmontagem
    expect(() => unmount()).not.toThrow();
  \});
 
  it("responde a mudanças de opção", () => \{
    const \{ result, rerender \} = renderHook(
      (\{ enabled \}) => useMyHook(\{ enabled \}),
      \{ initialProps: \{ enabled: false \} \}
    );
    expect(result.current.loading).toBe(false);
    rerender(\{ enabled: true \});
    expect(result.current.loading).toBe(true);
  \});
\});

Regras de Composição de Hooks

Hooks podem chamar outros hooks (esse é o modelo de composição).
Mantenha a cadeia de dependência rasa (hook A -> hook B está ok; A -> B -> C -> D é um mau sinal).
Se estiver compondo hooks, garanta que a limpeza se propague corretamente.
Use refs para quebrar ciclos de dependência de efeitos.


## Exemplo de Trabalho

### Exemplo 1: Usuário pergunta "Crie um hook para copiar texto para a área de transferência"

**Prompt do usuário:** "Preciso de um hook que copie texto para a área de transferência e mostre um estado de sucesso por 2 segundos."

**A resposta guiada pela skill produziria:**

```tsx
// hooks/use-clipboard.ts
import { useState, useCallback, useRef } from "react";

interface UseClipboardOptions {
  /** Quanto tempo mostrar o estado copiado em ms */
  successDuration?: number;
}

interface UseClipboardReturn {
  copied: boolean;
  copy: (text: string) => Promise<void>;
  error: Error | null;
}

export function useClipboard(
  options: UseClipboardOptions = {}
): UseClipboardReturn {
  const { successDuration = 2000 } = options;
  const [copied, setCopied] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const timeoutRef = useRef<ReturnType<typeof setTimeout>>();

  const copy = useCallback(
    async (text: string) => {
      if (typeof navigator === "undefined" || !navigator.clipboard) {
        setError(new Error("API da área de transferência não disponível"));
        return;
      }

      try {
        await navigator.clipboard.writeText(text);
        setCopied(true);
        setError(null);

        if (timeoutRef.current) clearTimeout(timeoutRef.current);
        timeoutRef.current = setTimeout(() => setCopied(false), successDuration);
      } catch (err) {
        setError(err instanceof Error ? err : new Error("Falha ao copiar"));
        setCopied(false);
      }
    },
    [successDuration]
  );

  return { copied, copy, error };
}

// hooks/use-clipboard.test.ts
import { renderHook, act } from "@testing-library/react";
import { useClipboard } from "./use-clipboard";
 
// Mock da API da área de transferência
Object.assign(navigator, {
  clipboard: { writeText: vi.fn().mockResolvedValue(undefined) },
});
 
describe("useClipboard", () => {
  it("copia texto e define copied como true", async () => {
    const { result } = renderHook(() => useClipboard());
    await act(async () => {
      await result.current.copy("hello");
    });
    expect(result.current.copied).toBe(true);
    expect(navigator.clipboard.writeText).toHaveBeenCalledWith("hello");
  });
 
  it("reseta copied após successDuration", async () => {
    vi.useFakeTimers();
    const { result } = renderHook(() =>
      useClipboard({ successDuration: 1000 })
    );
    await act(async () => {
      await result.current.copy("hello");
    });
    expect(result.current.copied).toBe(true);
    act(() => vi.advanceTimersByTime(1000));
    expect(result.current.copied).toBe(false);
    vi.useRealTimers();
  });
});

Regras de design - Nomenclatura, tipos de retorno, convenções de parâmetros.
Template de criação - Um ponto de partida para copiar e colar para qualquer novo hook.
Biblioteca de receitas - 6 implementações de hooks prontas para produção.
Template de teste - Estrutura de teste padronizada para hooks.
Critérios de extração - Quando extrair e quando não extrair.

Personalização

Adicione as convenções de nomenclatura de hooks do seu projeto.
Inclua hooks específicos do projeto como exemplos.
Especifique preferências de framework de teste (Vitest vs Jest).
Adicione requisitos de desempenho (por exemplo, "todos os hooks devem suportar o React Compiler").

Como Instalar

mkdir -p .claude/skills/custom-hooks-crafting
# Cole o conteúdo da Receita em .claude/skills/custom-hooks-crafting/SKILL.md

Gotchas

A limpeza do useEffect é executada antes de cada re-execução, não apenas na desmontagem - Projete funções de limpeza para lidar com ambos os casos.
Funções inicializadoras do useState são executadas apenas uma vez - useState(() => expensiveComputation()) é diferente de useState(expensiveComputation()).
Refs não disparam re-renderizações - Se você precisar que a UI atualize, você precisa de estado, não de refs.
Hooks personalizados compartilham lógica, não estado - Dois componentes chamando o mesmo hook recebem seu próprio estado independente.
Hooks não podem ser chamados condicionalmente - Mas use() no React 19 pode.

Alternativas

Abordagem	Quando Usar
Funções utilitárias simples	Lógica que não precisa de hooks do React
Componentes de ordem superior	Envolver comportamento em torno de um componente (padrão legado)
Render props	Compartilhar comportamento com controle de renderização (padrão legado)
Seletores Zustand	Estado compartilhado entre componentes (não apenas lógica compartilhada)

FAQs

Quando você deve extrair lógica para um hook personalizado em vez de mantê-la no componente?

Extraia quando o mesmo padrão useState + useEffect aparece em 2+ componentes.
Extraia quando a lógica de estado complexa obscurece a lógica de renderização.
Não extraia se a lógica for usada em um componente e for simples, ou se envolver um único useState.

Por que os nomes dos hooks personalizados devem começar com "use"?

O React impõe essa convenção para identificar funções que podem chamar outros hooks.
O linter usa o prefixo use para aplicar as Regras de Hooks (sem chamadas condicionais, sem chamadas em loops).
Sem o prefixo, o React não pode verificar o uso correto do hook no tempo de lint.

Qual é a convenção de tipo de retorno correta para um hook personalizado?

Valor único: retorne-o diretamente.
Valor + setter: retorne uma tupla [valor, setter] (como useState).
Múltiplos valores relacionados: retorne um objeto { valor, loading, error }.

Como você tipa o valor de retorno de um hook genérico como useLocalStorage em TypeScript?

function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void] {
  // T é inferido de initialValue
}

Como você torna um hook personalizado seguro para SSR?

Verifique typeof window !== "undefined" antes de acessar APIs do navegador como localStorage, navigator ou matchMedia.
Retorne um padrão sensato durante o SSR (por exemplo, false para useMediaQuery).

Gotcha: Dois componentes chamando o mesmo hook personalizado compartilham estado?

Não. Cada componente obtém sua própria instância de estado independente.
Hooks personalizados compartilham lógica, não estado.
Para estado compartilhado, use uma biblioteca de gerenciamento de estado como Zustand ou React Context.

Por que as funções retornadas de hooks devem ser envolvidas em useCallback?

Sem useCallback, a referência da função muda a cada renderização.
Componentes filhos que recebem a função como prop serão re-renderizados desnecessariamente.
Referências estáveis evitam re-renderizações em cascata.

Como você testa um hook personalizado usando React Testing Library?

import { renderHook, act } from "@testing-library/react";
import { useMyHook } from "./useMyHook";
 
it("retorna o estado inicial", () => {
  const { result } = renderHook(() => useMyHook());
  expect(result.current.data).toBeNull();
});
 
it("atualiza na ação", () => {
  const { result } = renderHook(() => useMyHook());
  act(() => result.current.reset());
  expect(result.current.data).toBeNull();
});

Gotcha: Qual é a diferença entre useState(fn) e useState(fn())?

useState(() => expensiveComputation()) executa a função apenas uma vez na renderização inicial (inicializador preguiçoso).
useState(expensiveComputation()) executa a função em cada renderização, desperdiçando computação.

Qual é o padrão useRef para evitar closures obsoletas em useEffect?

Armazene o callback mais recente em um ref: handlerRef.current = handler.
No efeito, chame handlerRef.current(...) em vez de handler(...).
Isso permite que o closure do efeito permaneça estável (dependências vazias), enquanto sempre chama a função mais recente.

Como você tipa o valor de retorno de useClickOutside em TypeScript?

function useClickOutside<T extends HTMLElement>(
  handler: () => void
): React.RefObject<T | null> {
  const ref = useRef<T | null>(null);
  // anexa listeners do documento, verifica ref.current.contains
  return ref;
}

Qual é a profundidade máxima recomendada para cadeias de composição de hooks?

Mantenha-as rasas: hook A chamando hook B está ok; A chamando B chamando C chamando D é um mau sinal.
Cadeias profundas dificultam a propagação da limpeza e a depuração.
Se você precisar de composição profunda, considere refatorar em hooks menos e mais focados.

Relacionado

Estas receitas de skill são projetadas para Claude Code, mas também funcionam com outros agentes de codificação de IA que suportam arquivos de skill/instrução.

Receita

O conteúdo completo do SKILL.md que você pode copiar para .claude/skills/custom-hooks-crafting/SKILL.md:

---
name: custom-hooks-crafting
description: "Criação de hooks React personalizados e reutilizáveis com TypeScript adequado. Use quando solicitado para: criar um hook, hook personalizado, extrair hook, hook reutilizável, composição de hooks, testar um hook."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Criação de Hooks Personalizados
 
Você é um especialista em criar hooks React personalizados. Cada hook que você cria segue princípios de design rigorosos, é totalmente tipado, seguro para SSR e testável.
 
## Regras de Design de Hooks
 
1. **Responsabilidade única** - Cada hook faz exatamente uma coisa.
2. **Nome começa com `use`** - Sempre prefixe com `use` (o React impõe isso).
3. **Convenções de tipo de retorno:**
   - Valor único: retorne o valor diretamente.
   - Valor + setter: retorne uma tupla `[valor, setter]` (como useState).
   - Múltiplos valores relacionados: retorne um objeto `{ valor, loading, error }`.
4. **Aceite configuração como um objeto** - Quando um hook recebe mais de 2 parâmetros, use um objeto de opções.
5. **Forneça padrões sensatos** - Cada opção deve ter um valor padrão.
6. **Limpe após você mesmo** - Sempre retorne funções de limpeza de useEffect.
7. **Segurança SSR** - Verifique `typeof window !== "undefined"` antes de acessar APIs do navegador.
8. **Referências estáveis** - Envolva funções retornadas em useCallback, envolva objetos retornados em useMemo.
 
## Template de Criação de Hook
 
```tsx
import \{ useState, useEffect, useCallback, useRef \} from "react";
 
interface UseMyHookOptions \{
  /** Descrição da opção */
  enabled?: boolean;
  /** Descrição da opção */
  interval?: number;
\}
 
interface UseMyHookReturn \{
  /** Descrição do valor de retorno */
  data: string | null;
  /** Descrição do valor de retorno */
  loading: boolean;
  /** Descrição do valor de retorno */
  error: Error | null;
  /** Descrição do valor de retorno */
  reset: () => void;
\}
 
/**
 * Descrição do que o hook faz e quando usá-lo.
 *
 * @example
 * const \{ data, loading, error \} = useMyHook(\{ enabled: true \});
 */
export function useMyHook(options: UseMyHookOptions = \{\}): UseMyHookReturn \{
  const \{ enabled = true, interval = 1000 \} = options;
 
  const [data, setData] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
 
  // Use ref para valores necessários em efeitos, mas que não devem disparar re-execuções
  const intervalRef = useRef(interval);
  intervalRef.current = interval;
 
  useEffect(() => \{
    if (!enabled) return;
 
    let cancelled = false;
    setLoading(true);
 
    async function fetchData() \{
      try \{
        const result = await someAsyncOperation();
        if (!cancelled) \{
          setData(result);
          setLoading(false);
        \}
      \} catch (err) \{
        if (!cancelled) \{
          setError(err instanceof Error ? err : new Error(String(err)));
          setLoading(false);
        \}
      \}
    \}
 
    fetchData();
    return () => \{ cancelled = true; \};
  \}, [enabled]);
 
  const reset = useCallback(() => \{
    setData(null);
    setLoading(false);
    setError(null);
  \}, []);
 
  return \{ data, loading, error, reset \};
\}

Receitas Comuns de Hooks

useDebounce

export function useDebounce<T>(value: T, delay: number): T \{
  const [debouncedValue, setDebouncedValue] = useState(value);
 
  useEffect(() => \{
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  \}, [value, delay]);
 
  return debouncedValue;
\}

useMediaQuery

export function useMediaQuery(query: string): boolean \{
  const [matches, setMatches] = useState(false);
 
  useEffect(() => \{
    if (typeof window === "undefined") return;
 
    const media = window.matchMedia(query);
    setMatches(media.matches);
 
    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
    media.addEventListener("change", listener);
    return () => media.removeEventListener("change", listener);
  \}, [query]);
 
  return matches;
\}

useClickOutside

export function useClickOutside<T extends HTMLElement>(
  handler: () => void
): React.RefObject<T | null> \{
  const ref = useRef<T | null>(null);
 
  useEffect(() => \{
    const listener = (event: MouseEvent | TouchEvent) => \{
      if (!ref.current || ref.current.contains(event.target as Node)) return;
      handler();
    \};
 
    document.addEventListener("mousedown", listener);
    document.addEventListener("touchstart", listener);
    return () => \{
      document.removeEventListener("mousedown", listener);
      document.removeEventListener("touchstart", listener);
    \};
  \}, [handler]);
 
  return ref;
\}

useLocalStorage

export function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void] \{
  const [storedValue, setStoredValue] = useState<T>(() => \{
    if (typeof window === "undefined") return initialValue;
    try \{
      const item = window.localStorage.getItem(key);
      return item ? (JSON.parse(item) as T) : initialValue;
    \} catch \{
      return initialValue;
    \}
  \});
 
  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => \{
      setStoredValue((prev) => \{
        const next = value instanceof Function ? value(prev) : value;
        if (typeof window !== "undefined") \{
          window.localStorage.setItem(key, JSON.stringify(next));
        \}
        return next;
      \});
    \},
    [key]
  );
 
  return [storedValue, setValue];
\}

useIntersectionObserver

interface UseIntersectionOptions \{
  threshold?: number;
  rootMargin?: string;
  triggerOnce?: boolean;
\}
 
export function useIntersectionObserver<T extends HTMLElement>(
  options: UseIntersectionOptions = \{\}
): [React.RefObject<T | null>, boolean] \{
  const \{ threshold = 0, rootMargin = "0px", triggerOnce = false \} = options;
  const ref = useRef<T | null>(null);
  const [isVisible, setIsVisible] = useState(false);
 
  useEffect(() => \{
    const element = ref.current;
    if (!element || typeof IntersectionObserver === "undefined") return;
 
    const observer = new IntersectionObserver(
      ([entry]) => \{
        setIsVisible(entry.isIntersecting);
        if (entry.isIntersecting && triggerOnce) \{
          observer.unobserve(element);
        \}
      \},
      \{ threshold, rootMargin \}
    );
 
    observer.observe(element);
    return () => observer.disconnect();
  \}, [threshold, rootMargin, triggerOnce]);
 
  return [ref, isVisible];
\}

usePrevious

export function usePrevious<T>(value: T): T | undefined \{
  const ref = useRef<T | undefined>(undefined);
 
  useEffect(() => \{
    ref.current = value;
  \});
 
  return ref.current;
\}

Quando Extrair um Hook

Extraia um hook personalizado quando:

O mesmo padrão useState + useEffect aparece em 2+ componentes.
Um componente tem lógica de estado complexa que obscurece a lógica de renderização.
Você precisa compartilhar comportamento (não UI) entre componentes.
Testar a lógica independentemente do componente seria valioso.

NÃO extraia um hook quando:

A lógica é usada em apenas um componente e é simples.
Você está apenas envolvendo um único useState (adiciona indireção sem benefício).
O "hook" não usa nenhum hook do React internamente (faça uma função simples).

Template de Teste

import \{ renderHook, act, waitFor \} from "@testing-library/react";
import \{ useMyHook \} from "./useMyHook";
 
describe("useMyHook", () => \{
  it("retorna o estado inicial", () => \{
    const \{ result \} = renderHook(() => useMyHook());
    expect(result.current.data).toBeNull();
    expect(result.current.loading).toBe(false);
    expect(result.current.error).toBeNull();
  \});
 
  it("atualiza o estado na ação", () => \{
    const \{ result \} = renderHook(() => useMyHook(\{ enabled: true \}));
    act(() => \{
      result.current.reset();
    \});
    expect(result.current.data).toBeNull();
  \});
 
  it("lida com operações assíncronas", async () => \{
    const \{ result \} = renderHook(() => useMyHook(\{ enabled: true \}));
    await waitFor(() => \{
      expect(result.current.loading).toBe(false);
    \});
    expect(result.current.data).toBeDefined();
  \});
 
  it("limpa na desmontagem", () => \{
    const \{ unmount \} = renderHook(() => useMyHook());
    // Verifica se não há erros ou avisos na desmontagem
    expect(() => unmount()).not.toThrow();
  \});
 
  it("responde a mudanças de opção", () => \{
    const \{ result, rerender \} = renderHook(
      (\{ enabled \}) => useMyHook(\{ enabled \}),
      \{ initialProps: \{ enabled: false \} \}
    );
    expect(result.current.loading).toBe(false);
    rerender(\{ enabled: true \});
    expect(result.current.loading).toBe(true);
  \});
\});

Regras de Composição de Hooks

Hooks podem chamar outros hooks (esse é o modelo de composição).
Mantenha a cadeia de dependência rasa (hook A -> hook B está ok; A -> B -> C -> D é um mau sinal).
Se estiver compondo hooks, garanta que a limpeza se propague corretamente.
Use refs para quebrar ciclos de dependência de efeitos.


## Exemplo de Trabalho

### Exemplo 1: Usuário pergunta "Crie um hook para copiar texto para a área de transferência"

**Prompt do usuário:** "Preciso de um hook que copie texto para a área de transferência e mostre um estado de sucesso por 2 segundos."

**A resposta guiada pela skill produziria:**

```tsx
// hooks/use-clipboard.ts
import { useState, useCallback, useRef } from "react";

interface UseClipboardOptions {
  /** Quanto tempo mostrar o estado copiado em ms */
  successDuration?: number;
}

interface UseClipboardReturn {
  copied: boolean;
  copy: (text: string) => Promise<void>;
  error: Error | null;
}

export function useClipboard(
  options: UseClipboardOptions = {}
): UseClipboardReturn {
  const { successDuration = 2000 } = options;
  const [copied, setCopied] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const timeoutRef = useRef<ReturnType<typeof setTimeout>>();

  const copy = useCallback(
    async (text: string) => {
      if (typeof navigator === "undefined" || !navigator.clipboard) {
        setError(new Error("API da área de transferência não disponível"));
        return;
      }

      try {
        await navigator.clipboard.writeText(text);
        setCopied(true);
        setError(null);

        if (timeoutRef.current) clearTimeout(timeoutRef.current);
        timeoutRef.current = setTimeout(() => setCopied(false), successDuration);
      } catch (err) {
        setError(err instanceof Error ? err : new Error("Falha ao copiar"));
        setCopied(false);
      }
    },
    [successDuration]
  );

  return { copied, copy, error };
}

// hooks/use-clipboard.test.ts
import { renderHook, act } from "@testing-library/react";
import { useClipboard } from "./use-clipboard";
 
// Mock da API da área de transferência
Object.assign(navigator, {
  clipboard: { writeText: vi.fn().mockResolvedValue(undefined) },
});
 
describe("useClipboard", () => {
  it("copia texto e define copied como true", async () => {
    const { result } = renderHook(() => useClipboard());
    await act(async () => {
      await result.current.copy("hello");
    });
    expect(result.current.copied).toBe(true);
    expect(navigator.clipboard.writeText).toHaveBeenCalledWith("hello");
  });
 
  it("reseta copied após successDuration", async () => {
    vi.useFakeTimers();
    const { result } = renderHook(() =>
      useClipboard({ successDuration: 1000 })
    );
    await act(async () => {
      await result.current.copy("hello");
    });
    expect(result.current.copied).toBe(true);
    act(() => vi.advanceTimersByTime(1000));
    expect(result.current.copied).toBe(false);
    vi.useRealTimers();
  });
});

Regras de design - Nomenclatura, tipos de retorno, convenções de parâmetros.
Template de criação - Um ponto de partida para copiar e colar para qualquer novo hook.
Biblioteca de receitas - 6 implementações de hooks prontas para produção.
Template de teste - Estrutura de teste padronizada para hooks.
Critérios de extração - Quando extrair e quando não extrair.

Personalização

Adicione as convenções de nomenclatura de hooks do seu projeto.
Inclua hooks específicos do projeto como exemplos.
Especifique preferências de framework de teste (Vitest vs Jest).
Adicione requisitos de desempenho (por exemplo, "todos os hooks devem suportar o React Compiler").

Como Instalar

mkdir -p .claude/skills/custom-hooks-crafting
# Cole o conteúdo da Receita em .claude/skills/custom-hooks-crafting/SKILL.md

Gotchas

A limpeza do useEffect é executada antes de cada re-execução, não apenas na desmontagem - Projete funções de limpeza para lidar com ambos os casos.
Funções inicializadoras do useState são executadas apenas uma vez - useState(() => expensiveComputation()) é diferente de useState(expensiveComputation()).
Refs não disparam re-renderizações - Se você precisar que a UI atualize, você precisa de estado, não de refs.
Hooks personalizados compartilham lógica, não estado - Dois componentes chamando o mesmo hook recebem seu próprio estado independente.
Hooks não podem ser chamados condicionalmente - Mas use() no React 19 pode.

Alternativas

Abordagem	Quando Usar
Funções utilitárias simples	Lógica que não precisa de hooks do React
Componentes de ordem superior	Envolver comportamento em torno de um componente (padrão legado)
Render props	Compartilhar comportamento com controle de renderização (padrão legado)
Seletores Zustand	Estado compartilhado entre componentes (não apenas lógica compartilhada)

FAQs

Quando você deve extrair lógica para um hook personalizado em vez de mantê-la no componente?

Extraia quando o mesmo padrão useState + useEffect aparece em 2+ componentes.
Extraia quando a lógica de estado complexa obscurece a lógica de renderização.
Não extraia se a lógica for usada em um componente e for simples, ou se envolver um único useState.

Por que os nomes dos hooks personalizados devem começar com "use"?

O React impõe essa convenção para identificar funções que podem chamar outros hooks.
O linter usa o prefixo use para aplicar as Regras de Hooks (sem chamadas condicionais, sem chamadas em loops).
Sem o prefixo, o React não pode verificar o uso correto do hook no tempo de lint.

Qual é a convenção de tipo de retorno correta para um hook personalizado?

Valor único: retorne-o diretamente.
Valor + setter: retorne uma tupla [valor, setter] (como useState).
Múltiplos valores relacionados: retorne um objeto { valor, loading, error }.

Como você tipa o valor de retorno de um hook genérico como useLocalStorage em TypeScript?

function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void] {
  // T é inferido de initialValue
}

Como você torna um hook personalizado seguro para SSR?

Verifique typeof window !== "undefined" antes de acessar APIs do navegador como localStorage, navigator ou matchMedia.
Retorne um padrão sensato durante o SSR (por exemplo, false para useMediaQuery).

Gotcha: Dois componentes chamando o mesmo hook personalizado compartilham estado?

Não. Cada componente obtém sua própria instância de estado independente.
Hooks personalizados compartilham lógica, não estado.
Para estado compartilhado, use uma biblioteca de gerenciamento de estado como Zustand ou React Context.

Por que as funções retornadas de hooks devem ser envolvidas em useCallback?

Sem useCallback, a referência da função muda a cada renderização.
Componentes filhos que recebem a função como prop serão re-renderizados desnecessariamente.
Referências estáveis evitam re-renderizações em cascata.

Como você testa um hook personalizado usando React Testing Library?

import { renderHook, act } from "@testing-library/react";
import { useMyHook } from "./useMyHook";
 
it("retorna o estado inicial", () => {
  const { result } = renderHook(() => useMyHook());
  expect(result.current.data).toBeNull();
});
 
it("atualiza na ação", () => {
  const { result } = renderHook(() => useMyHook());
  act(() => result.current.reset());
  expect(result.current.data).toBeNull();
});

Gotcha: Qual é a diferença entre useState(fn) e useState(fn())?

useState(() => expensiveComputation()) executa a função apenas uma vez na renderização inicial (inicializador preguiçoso).
useState(expensiveComputation()) executa a função em cada renderização, desperdiçando computação.

Qual é o padrão useRef para evitar closures obsoletas em useEffect?

Armazene o callback mais recente em um ref: handlerRef.current = handler.
No efeito, chame handlerRef.current(...) em vez de handler(...).
Isso permite que o closure do efeito permaneça estável (dependências vazias), enquanto sempre chama a função mais recente.

Como você tipa o valor de retorno de useClickOutside em TypeScript?

function useClickOutside<T extends HTMLElement>(
  handler: () => void
): React.RefObject<T | null> {
  const ref = useRef<T | null>(null);
  // anexa listeners do documento, verifica ref.current.contains
  return ref;
}

Qual é a profundidade máxima recomendada para cadeias de composição de hooks?

Mantenha-as rasas: hook A chamando hook B está ok; A chamando B chamando C chamando D é um mau sinal.
Cadeias profundas dificultam a propagação da limpeza e a depuração.
Se você precisar de composição profunda, considere refatorar em hooks menos e mais focados.

Skill de Criação de Hooks Personalizados - Uma receita Claude Code para criar hooks React reutilizáveis e bem testados

Buscar na documentação

Skill de Criação de Hooks Personalizados - Uma receita Claude Code para criar hooks React reutilizáveis e bem testados