Hướng dẫn Cài đặt và Sử dụng TanStack Query (React Query v5) trong Next.js App Router từ A-Z

# Dùng pnpm (khuyên dùng)
pnpm add @tanstack/react-query
pnpm add -D @tanstack/react-query-devtools

# Hoặc dùng npm / yarn / bun
# npm install @tanstack/react-query && npm install -D @tanstack/react-query-devtools
# yarn add @tanstack/react-query && yarn add -D @tanstack/react-query-devtools

"use client";

import {
  QueryClient,
  QueryClientProvider,
  isServer,
} from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
import { useState } from "react";

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // Dữ liệu được coi là mới trong 1 phút (tránh refetch liên tục)
        staleTime: 60 * 1000,
        // Tắt tự động refetch khi chuyển tab để tiết kiệm request
        refetchOnWindowFocus: false,
        // Thử lại 1 lần nếu network gặp sự cố
        retry: 1,
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined = undefined;

function getQueryClient() {
  if (isServer) {
    // Server: Luôn tạo một queryClient mới cho mỗi request
    return makeQueryClient();
  } else {
    // Browser: Tạo một singleton client duy nhất nếu chưa có
    if (!browserQueryClient) browserQueryClient = makeQueryClient();
    return browserQueryClient;
  }
}

export default function QueryProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const queryClient = getQueryClient();

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      {/* DevTools chỉ hiển thị ở môi trường Development */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

"use client";

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

// 1. Interface dữ liệu
export interface Post {
  id: string;
  title: string;
  slug: string;
  views: number;
}

// 2. Hàm gọi API thuần túy
async function fetchPosts(): Promise<Post[]> {
  const res = await fetch("/api/blog/posts");
  if (!res.ok) throw new Error("Không thể tải danh sách bài viết");
  return res.json();
}

async function fetchPostDetail(slug: string): Promise<Post> {
  const res = await fetch(`/api/blog/posts/${slug}`);
  if (!res.ok) throw new Error("Không tìm thấy bài viết");
  return res.json();
}

// 3. Custom Hook useQuery
export function usePostsQuery() {
  return useQuery({
    queryKey: ["posts"],
    queryFn: fetchPosts,
    staleTime: 5 * 60 * 1000, // Dữ liệu client cache trong 5 phút
  });
}

export function usePostDetailQuery(slug: string) {
  return useQuery({
    queryKey: ["post", slug],
    queryFn: () => fetchPostDetail(slug),
    enabled: Boolean(slug), // Chỉ chạy query khi có slug
  });
}

"use client";

import { usePostsQuery } from "@/src/services/blog/useBlogQueries";

export function PostList() {
  const { data: posts, isLoading, isError, error, refetch } = usePostsQuery();

  if (isLoading) {
    return <div className="p-4 text-zinc-400">Đang tải bài viết...</div>;
  }

  if (isError) {
    return (
      <div className="p-4 text-red-400">
        Lỗi: {error.message}
        <button onClick={() => refetch()} className="ml-2 underline">Thử lại</button>
      </div>
    );
  }

  return (
    <div className="grid gap-4">
      {posts?.map((post) => (
        <div key={post.id} className="p-4 rounded-xl bg-zinc-900 border border-zinc-800">
          <h3 className="font-semibold text-zinc-100">{post.title}</h3>
          <span className="text-xs text-zinc-500">{post.views} lượt xem</span>
        </div>
      ))}
    </div>
  );
}

"use client";

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

interface CreatePostPayload {
  title: string;
  content: string;
}

export function useCreatePostMutation() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (newPost: CreatePostPayload) => {
      const res = await fetch("/api/admin/blog", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(newPost),
      });
      if (!res.ok) throw new Error("Tạo bài viết thất bại");
      return res.json();
    },
    onSuccess: () => {
      // ⚡ Làm mới cache của danh sách bài viết
      queryClient.invalidateQueries({ queryKey: ["posts"] });
      queryClient.invalidateQueries({ queryKey: ["adminPosts"] });
    },
    onError: (err) => {
      console.error("Lỗi:", err.message);
    },
  });
}

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from "@tanstack/react-query";
import { PostList } from "@/src/features/blog/components/PostList";

// Server Component
export default async function BlogPage() {
  const queryClient = new QueryClient();

  // 1. Fetch dữ liệu trước trên Server
  await queryClient.prefetchQuery({
    queryKey: ["posts"],
    queryFn: async () => {
      const res = await fetch("https://api.duynoa.com/api/blog/posts");
      return res.json();
    },
  });

  return (
    // 2. Hydrate dữ liệu sang Client Component
    <HydrationBoundary state={dehydrate(queryClient)}>
      <main className="container mx-auto py-12">
        <h1 className="text-3xl font-bold text-zinc-100 mb-6">Blog Công Nghệ</h1>
        {/* PostList ở client sẽ nhận data ngay lập tức mà không cần loading */}
        <PostList />
      </main>
    </HydrationBoundary>
  );
}