كيفية استخدام React Query لإدارة حالة الخادم في 2026

التثبيت

npm install @tanstack/react-query

إعداد المزوّد (Provider)

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            staleTime: 5 * 60 * 1000, // 5 minutes
            retry: 1,
        },
    },
});

function App() {
    return (
        <QueryClientProvider client={queryClient}>
            <YourApp />
        </QueryClientProvider>
    );
}

استعلام أساسي

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

function Users() {
    const { data, isLoading, error } = useQuery({
        queryKey: ['users'],
        queryFn: async () => {
            const res = await fetch('/api/users');
            return res.json();
        },
    });

    if (isLoading) return <p>Loading...</p>;
    if (error) return <p>Error: {error.message}</p>;

    return (
        <ul>
            {data.map(user => (
                <li key={user.id}>{user.name}</li>
            ))}
        </ul>
    );
}

التعديلات (Mutations)

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

function CreateUser() {
    const queryClient = useQueryClient();

    const mutation = useMutation({
        mutationFn: (newUser) => {
            return fetch('/api/users', {
                method: 'POST',
                body: JSON.stringify(newUser),
            });
        },
        onSuccess: () => {
            // Invalidate and refetch
            queryClient.invalidateQueries({ queryKey: ['users'] });
        },
    });

    return (
        <button
            onClick={() => mutation.mutate({ name: 'New User' })}
            disabled={mutation.isPending}
        >
            {mutation.isPending ? 'Creating...' : 'Create User'}
        </button>
    );
}

التحديثات التفاؤلية (Optimistic Updates)

const mutation = useMutation({
    mutationFn: updateTodo,
    onMutate: async (newTodo) => {
        await queryClient.cancelQueries({ queryKey: ['todos'] });

        const previousTodos = queryClient.getQueryData(['todos']);

        queryClient.setQueryData(['todos'], (old) =>
            old.map(t => t.id === newTodo.id ? newTodo : t)
        );

        return { previousTodos };
    },
    onError: (err, newTodo, context) => {
        queryClient.setQueryData(['todos'], context.previousTodos);
    },
    onSettled: () => {
        queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
});