Our review

Generates a custom React Query hook for data fetching with proper typing.

Strengths

Strong typing aligned with backend DTOs
Automatic cache management with invalidation after mutations
Follows naming conventions and project structure guidelines

Limitations

Requires existing Axios configuration and defined backend endpoints
Does not handle complex cases like parallel queries or advanced pagination

When to use it

Use this skill when you need to create a React Query hook to interact with an existing REST API in a React application.

When not to use it

Avoid this skill if you are using a different state management library (e.g., Redux, Zustand) or if the API is not yet defined.

Examples

Create a GET query hook for tasks

Generate a React Query hook for fetching a task by ID: GET /tasks/:id with response type Task.

Create a mutation hook to create a project

Generate a React Query mutation hook for creating a project via POST /projects. The hook should invalidate the 'projects' query on success.

Create a query hook for user list with pagination

Generate a React Query hook for fetching a paginated list of users from GET /users?page=1&limit=20. The hook should accept page and limit parameters and return data with total count.

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!"

Custom React Query Hook

Recommended for