TanStack Query 101 with Next.js

ek3nk4r 2025-01-25

0 11 خواندن این مطلب 5 دقیقه زمان میبرد

پیشنهاد ویژه

خرید فالوور واقعی خرید لایک اینستاگرام خرید ویو اینستاگرام خرید فالوور اینستاگرام

در توسعه وب مدرن، مدیریت وضعیت سرور و واکشی داده ها می تواند یک چالش باشد. وارد کنید پرس و جوی TanStack (که قبلا به عنوان React Query شناخته می شد)، یک کتابخانه قدرتمند که واکشی داده ها، کش کردن، همگام سازی و موارد دیگر را ساده می کند. هنگامی که با Next.jsیک فریم ورک محبوب React برای برنامه‌های رندر شده توسط سرور، می‌توانید به راحتی برنامه‌هایی با عملکرد بالا و مقیاس‌پذیر بسازید.

در این پست وبلاگ، اصول استفاده از TanStack Query با Next.js را مرور خواهیم کرد. چه مبتدی یا یک توسعه دهنده با تجربه باشید، این راهنما به شما کمک می کند تا با TanStack Query شروع کنید و پتانسیل کامل آن را باز کنید.

فهرست مطالب

TanStack Query چیست؟

TanStack Query یک مدیریت حالت ناهمگام است. این ابزارها را برای:

واکشی داده ها: داده ها را به راحتی از API ها واکشی کنید.
ذخیره سازی: داده ها را به صورت خودکار ذخیره کنید تا از درخواست های شبکه غیر ضروری جلوگیری شود.
به روز رسانی پس زمینه: رابط کاربری خود را با داده های جدید به روز نگه دارید.
رسیدگی به خطا: مدیریت خطا و تلاش مجدد را ساده کنید.
Devtools: پرس و جوهای خود را با ابزارهای توسعه داخلی داخلی اشکال زدایی و تجسم کنید.

هنگامی که با Next.js ترکیب شود، TanStack Query به یک نیروگاه برای ساخت برنامه های رندر شده توسط سرور، تولید استاتیک یا ارائه شده توسط مشتری تبدیل می شود.

چرا از TanStack Query با Next.js استفاده کنیم؟

Next.js یک چارچوب همه کاره است که از رندر سمت سرور (SSR)، تولید سایت استاتیک (SSG) و رندر سمت مشتری (CSR) پشتیبانی می کند. TanStack Query Next.js را توسط:

ساده‌سازی واکشی داده‌ها: دستی دیگر وجود ندارد useEffect قلاب یا مدیریت پیچیده دولت.
بهبود عملکرد: ذخیره خودکار و به روز رسانی پس زمینه درخواست های غیر ضروری شبکه را کاهش می دهد.
افزایش تجربه توسعه دهندگان: ابزارهای توسعه داخلی، اشکال زدایی را آسان می کند.
پشتیبانی از رندر هیبریدی: به طور یکپارچه با SSR، SSG و CSR کار می کند.

شروع به کار: TanStack Query با Next.js

بیایید به مراحل عملی راه‌اندازی و استفاده از TanStack Query در پروژه Next.js بپردازیم.

1. یک پروژه Next.js راه اندازی کنید

اگر قبلاً پروژه Next.js ندارید، آن را ایجاد کنید:

npx create-next-app@latest my-tanstack-query-app
cd my-tanstack-query-app

2. TanStack Query را نصب کنید

بسته های مورد نیاز را نصب کنید:

npm install @tanstack/react-query @tanstack/react-query-devtools

@tanstack/react-query: کتابخانه اصلی برای مدیریت پرس و جوها.
@tanstack/react-query-devtools: ابزاری برای اشکال زدایی و تجسم پرس و جوها.

3. QueryClient را تنظیم کنید

این QueryClient قلب TanStack Query است. حافظه پنهان را مدیریت می کند و زمینه را برای پرس و جوهای شما فراهم می کند.

ایجاد یک providers.js فایل در ریشه پروژه خود:

// providers.js
"use client"; // Mark this as a Client Component

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

const queryClient = new QueryClient();

export default function Providers({ children }) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

4. برنامه خود را با QueryClientProvider بپیچید

در شما app/layout.js، برنامه خود را با Providers جزء:

// app/layout.js
import Providers from "../providers";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

5. واکشی داده ها با `useQuery`

اکنون که همه چیز تنظیم شده است، بیایید با استفاده از آن مقداری داده واکشی کنیم useQuery قلاب

یک صفحه جدید ایجاد کنید، به عنوان مثال، app/page.js:

// app/page.js
"use client"; // Mark this as a Client Component

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

async function fetchPosts() {
  const res = await fetch("https://jsonplaceholder.typicode.com/posts");
  if (!res.ok) {
    throw new Error("Failed to fetch posts");
  }
  return res.json();
}

export default function Home() {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ["posts"],
    queryFn: fetchPosts,
  });

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

  return (
    <div>
      <h1>Posts</h1>
      <ul>
        {data.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
}

6. مفاهیم کلیدی

کلیدهای پرس و جو

کلیدهای پرس و جو شناسه های منحصر به فردی برای درخواست های شما هستند. آنها می توانند رشته یا آرایه باشند.
مثال: ["posts", 1] برای واکشی یک پست خاص

توابع پرس و جو

تابع query یک تابع ناهمزمان است که داده ها را برمی گرداند.
مثال: fetchPosts در کد بالا

ایالات پرس و جو

isLoading: درست زمانی که داده ها برای اولین بار واکشی می شوند.
isError: اگر پرس و جو با خطا مواجه شود درست است.
error: حاوی شی خطا if است isError درست است.
data: حاوی داده های واکشی شده پس از موفقیت آمیز بودن پرس و جو است.

7. واکشی اولیه داده با SSR

Next.js از رندر سمت سرور (SSR) پشتیبانی می کند. با استفاده از TanStack Query می توانید داده ها را از قبل بر روی سرور واکشی کنید و آن ها را روی کلاینت هیدراته کنید.

در اینجا نمونه ای از واکشی اولیه داده در صفحه Next.js آمده است:

// app/page.js
import { dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";
import Posts from "../components/Posts";

async function fetchPosts() {
  const res = await fetch("https://jsonplaceholder.typicode.com/posts");
  if (!res.ok) {
    throw new Error("Failed to fetch posts");
  }
  return res.json();
}

export default async function Home() {
  const queryClient = new QueryClient();

  await queryClient.prefetchQuery({
    queryKey: ["posts"],
    queryFn: fetchPosts,
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Posts />
    </HydrationBoundary>
  );
}

در Posts جزء، می توانید استفاده کنید useQuery برای دسترسی به داده های از پیش واکشی شده:

// components/Posts.js
"use client";

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

export default function Posts() {
  const { data } = useQuery({
    queryKey: ["posts"],
  });

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

8. React Query Devtools

React Query Devtools برای اشکال زدایی فوق العاده مفید است. آنها وضعیت جستجوها، حافظه پنهان و موارد دیگر را نشان می دهند.

برای فعال کردن آنها، را اضافه کنید ReactQueryDevtools جزء به شما providers.js فایل (همانطور که قبلا نشان داده شد). می‌توانید ابزارهای توسعه‌دهنده را با یک دکمه در گوشه سمت چپ پایین برنامه خود تغییر دهید.

9. الگوهای رایج

صفحه بندی

استفاده کنید useQuery با یک کلید پرس و جو پویا برای مدیریت صفحه بندی قلاب کنید:

const { data } = useQuery({
  queryKey: ["posts", page],
  queryFn: () => fetchPosts(page),
});

پرس و جوهای بی نهایت

برای بارگذاری بی نهایت، از useInfiniteQuery قلاب:

const { data, fetchNextPage } = useInfiniteQuery({
  queryKey: ["posts"],
  queryFn: ({ pageParam = 1 }) => fetchPosts(pageParam),
  getNextPageParam: (lastPage, allPages) => lastPage.nextPage,
});

10. نتیجه گیری

TanStack Query یک تغییر دهنده بازی برای مدیریت وضعیت سرور در برنامه های Next.js است. با حافظه پنهان، به‌روزرسانی‌های پس‌زمینه و مدیریت خطا، واکشی داده‌ها را ساده می‌کند و عملکرد را بهبود می‌بخشد.

این راهنما اصول اولیه را پوشش می‌دهد، اما TanStack Query دارای بسیاری از ویژگی‌های پیشرفته مانند جهش، به‌روزرسانی‌های خوش‌بینانه و موارد دیگر است. برای یادگیری بیشتر اسناد رسمی را بررسی کنید.

اکنون که اصول اولیه را یاد گرفته اید، زمان شروع ساختن است! کد نویسی مبارک! 🚀

مطالعه بیشتر: