Dev Create Hook

Create a custom hook following docs/ARCHITECTURE.md section 4.4.

Hook: $ARGUMENTS

Steps

1. Read docs/ARCHITECTURE.md section 4.4.

1. Determine the type:

• Query (data reading) -> useQuery + service + adapter
• Mutation (write/delete) -> useMutation + query invalidation
• Pure logic (no API) -> useState + useMemo + useEffect

1. Create the hook in hooks/use[Name].ts:

Query Hook Template

import { useQuery, keepPreviousData } from '@tanstack/react-query'
import { xxxService } from '../services/xxx-service'
import { xxxAdapter } from '../adapters/xxx-adapter'

interface UseXxxOptions {
  page: number
  pageSize?: number
}

export function useXxx(options: UseXxxOptions) {
  const { page, pageSize = 20 } = options

  const { data, isLoading, isFetching, error, refetch } = useQuery({
    queryKey: ['xxx', { page, pageSize }],
    queryFn: async () => {
      const response = await xxxService.list({ page, pageSize })
      return xxxAdapter.toXxxList(response.data)
    },
    staleTime: 5 * 60 * 1000,
    placeholderData: keepPreviousData,
  })

  return { data, isLoading, isFetching, error, refetch }
}

Mutation Hook Template

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { xxxService } from '../services/xxx-service'
import { xxxAdapter } from '../adapters/xxx-adapter'

export function useCreateXxx() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (input: CreateXxxInput) => {
      const payload = xxxAdapter.toCreatePayload(input)
      const response = await xxxService.create(payload)
      return xxxAdapter.toXxx(response.data)
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['xxx'] })
    },
  })
}

1. Required: use prefix, staleTime for queries, queryKey as array, adapter in queryFn.

1. Connect the layers: service -> adapter -> React Query

1. Validate: npx tsc --noEmit

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HerbertJulio
• Source: HerbertJulio/specialist-agent
• License: MIT
• Homepage: https://specialistagent.com.br

Install and usage instructions live in the source repository linked above.