Notre avis

Génère un hook React Query typé pour interagir avec une API, en suivant les conventions du projet.

Points forts

Respecte les conventions de nommage et de typage du projet
Lit le backend pour assurer la cohérence des endpoints et des types
Gère correctement le cache et l'invalidation après mutation

Limites

Nécessite que le backend soit déjà défini et accessible
Ne couvre pas les cas de pagination ou polling avancés

Quand l'utiliser

Lors de l'ajout d'une nouvelle intégration API nécessitant un hook React Query typé et fiable.

Quand l'éviter

Pour des appels API simples sans gestion d'état ou quand la structure du backend change fréquemment.

Exemples

Create useGetTasks query hook

Create a custom hook useGetTasks that fetches a list of tasks from GET /api/tasks with proper typing and query key.

Create useCreateProject mutation hook

Generate a useCreateProject mutation hook that posts to POST /api/projects and invalidates the projects list cache on success.

Create useUpdateTask mutation hook with ID

Write a useUpdateTask mutation hook that sends a PATCH request to /api/tasks/:id and invalidates the single task and task list caches.

name: react-query-hook description: Generate a custom React Query hook for data fetching with proper typing. Use when creating API integration hooks.

Generate React Query Hook

Create a custom hook using TanStack Query for data fetching.

Important: Follow the Learning Mode guidelines in _templates/learning-mode.md

Arguments

$ARGUMENTS - Hook name or API endpoint (e.g., "useTasks", "GET /projects/:id")

Pre-flight (BAT BUOC)

Truoc khi tao hook, DOC:

apps/web/src/services/api.ts — confirm Axios instance config
Backend controller tuong ung — confirm endpoint URL + response type
.context/research/PITFALLS.md > React section — TanStack Query cache stale
.context/research/CONVENTIONS.md > API Response Format

Instructions

Step 1: Clarify (Query vs Mutation, parameters)

Step 2: Read backend code (KHONG SKIP) — confirm endpoint URL + data shape

Step 3: Create the hook

Query (GET):

import { useQuery } from '@tanstack/react-query';
import { api } from '@/services/api';

export const use[Name] = (id: string) => {
  return useQuery({
    queryKey: ['[name]', id],
    queryFn: async () => {
      const { data } = await api.get<[Type]>(`/[endpoint]/${id}`);
      return data;
    },
    enabled: !!id,
  });
};

Mutation (POST/PATCH/DELETE):

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '@/services/api';

export const use[Name] = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: async (input: [Type]) => {
      const { data } = await api.post('/[endpoint]', input);
      return data;
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['[related]'] });
    },
  });
};

Code Standards

Naming: use[Action][Resource] — useGetTasks, useCreateProject
Query Keys: Array ['resource', id, params]
API client: LUON dung @/services/api — KHONG tao Axios instance moi
Types: Match backend DTOs — KHONG tu bia type
Response: Object truc tiep (khong wrapper), list { data, total, page, limit }

Pitfalls

enabled: !!dependency cho dependent queries
invalidateQueries() sau mutation — tranh stale cache
Destructure dung: const { data } = await api.get(...) — data la response body

After Completion

Remind user: "Test hook trong component" + "Update PROGRESS.md!"

Créer un hook React Query

Recommandé pour