Our review

Generates a typed React Query hook for API interactions, adhering to project conventions.

Strengths

Enforces naming and typing conventions based on existing project code
Reads backend code to ensure endpoint and type consistency
Handles cache invalidation properly after mutations

Limitations

Requires the backend to be already defined and accessible
Does not cover advanced pagination or polling scenarios

When to use it

When adding a new API integration that needs a reliable, typed React Query hook.

When not to use it

For simple one-off API calls without state management or when backend structure is frequently changing.

Examples

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

Generate React Query Hook

Recommended for

Our review

Strengths

Limitations

Security analysis

Examples

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

Arguments

Pre-flight (BAT BUOC)

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):

Mutation (POST/PATCH/DELETE):

Code Standards

Pitfalls

After Completion

Next.js App Router Expert

README Generator

API Documentation Writer