آموزش نصب و کانفیگ React Query نسخه 5

تو مقاله آموزش نصب و کانفیگ React Query قصد داریم تا نگاهی کامل به اولین قدم از استفاده از آخرین نسخه ری اکت کوئری یعنی نسخه 5 بندازیم و ببینیم این لایبرری دوست داشتنی را چطور میتونیم نصب و کانفیگ کنیم و چه تنظیمات و اقداماتی مهمی را هم همان ابتدای کار باید رعایت کنیم.

مواردی که قراره در این مقاله باهم یادبگیریم عبارت اند از:

• آموزش نصب React Query
• آموزش کانفیگ اولیه React Query
• تنظیمات و رفتارهای پیشفرض مهم React Query
• افزودن React Query Devtools و کاربردهای آن

نصب React Query

نصب React Query نسخه 5 خیلی آسونه و ما میتونیم بشکل زیر و با استفاده از هرکدام از Package Manager هایی چون npm, yarn, pnpm, bun اونرو نصب و به پروژه ری اکتی خودمون اضافش کنیم:

 npm i @tanstack/react-query
# یا
 pnpm add @tanstack/react-query
# یا
 yarn add @tanstack/react-query
# یا
 bun add @tanstack/react-query

به این نکته توجه داشته باشید که ری اکت کوئری فقط در مرورگرهای مدرنی که بالاتر از نسخه های زیر باشن پشتیبانی میشه:

Chrome >= 91
Firefox >= 90
Edge >= 91
Safari >= 15
iOS >= 15
Opera >= 77

همچنین پیشنهاد میشه که پلاگین ESLint Plugin Query را هم به عنوان یک Dev Dependency در پروژتون داشته باشید. این پلاگین کمک میکنه جلوی برخی باگ ها و ناسازگاری ها گرفته بشه:

 npm i -D @tanstack/eslint-plugin-query
# یا
 pnpm add -D @tanstack/eslint-plugin-query
# یا
 yarn add -D @tanstack/eslint-plugin-query
# یا
 bun add -D @tanstack/eslint-plugin-query

شروع به کار و کانفیگ React Query

برای کانفیگ و استفاده از React Query توی پروژمون نیازه تا یک کانفیگ ساده ای را انجام و provider ری اکت کوئری که در واقع یک کانتکست ری اکتی هست را به دور کل app خودمون اضافه کنیم:

import React from "react";
import ReactDOM from "react-dom/client";
import { createBrowserRouter, RouterProvider } from "react-router-dom";
import { routesData } from "./data/routes-data.tsx";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const router = createBrowserRouter(routesData);

const client = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <QueryClientProvider client={client}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  </React.StrictMode>
);

نکته: توجه داشته باشید که شما فقط میتونید در جاهایی از قابلیت های ری اکت کوئری استفاده کنید که اون جای مدنظر شما تحت پوشش provider ری اکت کوئری باشه. در مثال بالا ما تمامی روت های ری اکتی خودمون را تحت پوشش ری اکت کوئری در آوردیم. بنابر این در کل پروژه میتونیم از React Query استفاده کنیم. مثلا در نمونه کد پایین ما صرفا در کامپوننت todos میتونیم از ری اکت کوئری استفاده کنیم.

// Create a client
const queryClient = new QueryClient()

function App() {
  return (
    // Provide the client to your App
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  )
}

بریم حالا کدهای بالارو یکم ببریم زیر ذره بین و ببینیم هر قسمت دقیقا داره چکار میکنه:

• QueryClientProvider: این provider که در واقع یک context هستش و به ما اجازه میده تا از ری اکت کوئری در کامپوننت های فرزندی که این provider به دور اونها انداخته یا اصطلاحا wrap شدن استفاده کنیم و علاوه بر اون باعث میشه خود ری اکت کوئری هم در پشت صحنه دستش به دسترسی به بخش های مختلف کد جهت مدیریت مثلا سیستم cache باز باشه.
• QueryClient: این در واقع هسته اصلی ری اکت کوئری ما هستش و سیستم cache و خیلی چیزهای دیگه ری اکت کوئری در پشت صحنه بوسیله این QueryClient مدیریت و انجام میشه.

با همین کانفیگ ساده میتونیم React Query را به پروژه خودمون اضافه کنیم. حالا برای اینکه مطمئن بشید که ری اکت کوئری به پروژه شما اضافه شده و کار میکنه، کافیه تا در یکی از صفحات یا کامپوننت های خودتون کد زیر را بنویسید:

export const PostsList = () => {
  const { data, isFetching } = useQuery({
    queryKey: ["posts"],
    queryFn: () => {
      return axios.get("https://jsonplaceholder.typicode.com/posts");
    },
  });

  return (
    <div>
      <p>لیست پست ها</p>
    </div>
  );
};

در کدبالا ما بوسیله هوک useQuery که کاربردش در http request هایی که متدشون GET هستشه اومدیم لیست پست هارو از آدرس https://jsonplaceholder.typicode.com/posts دریافت کردیم.

کد بالارو اجرا کنید و network مرورگر را باز کنید تا ببینید که آیا درخواست GET به آدرس ذکر شده ارسال میشه یا خیر و درصورتی که چنین درخواستی وجود داشت یعنی کانفیگ و نصب React Query ما به درستی انجام شده.

در بالا صرفا مثالی را از یکی از هوک های ری اکت کوئری دیدیم و اصلا نگران سینتکس و نحوه استفاده ازشون نباشید، چراکه هم در دوره آموزش react query و هم در مقالات بعدی اونهارو بطور کامل آموزش داده ایم. 

افزودن React Query Devtools به پروژه

ابزار Devtools در React Query به ما اجازه میده تا با یک ظاهر گرافیکی تمیز و کاربردی، بخش زیادی از اتفاقاتی که در دل ری اکت کوئری میوفته را ببینیم. همچنین این ابزار کار network خود مرورگر را هم برای ما انجام میده و این  ابزار کاربردی که فقط و فقط هم در حالت Development در دسترسه کار مارو در دیباگ کردن و فهمیدن اینکه توی هوک های ری اکت کوئری و پشت صحنه چه اتفاقی میوفته راحت تر میکنه.

در زیر صرفا میتونید ببینید چطور این ابزار رو به پروژه اضافه کنید. اما در دوره آموزش ری اکت کوئری وبسایت وسپار میتونید کامل تر این ابزار رو یاد بگیرید.

ابتدا ابزار Devtools را از طریق یکی از دستورهای زیر نصب کنید:

 npm i @tanstack/react-query-devtools
# یا
 pnpm add @tanstack/react-query-devtools
# یا
 yarn add @tanstack/react-query-devtools
# یا
 bun add @tanstack/react-query-devtools

و در نهایت در داخل QueryClientProvider که قبل تر به  دور کل اپلیکیشنمون اضافش کردیم، کامپوننت زیر را هم اضافه میکنیم:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

تنظیمات و رفتارهای پیشرفرض React Query

ما به 2 شکل میتونیم تنظیماتی را برروی React Query اعمال کنیم، یکی از روش ها اعمال تنظیمات بصورت عمومی و کلی هست، یکی دیگه هم اعمال تنظیمات تک به تک روی موارد دلخواه و استفاده های دلخواه ما هستش.

اعمال تنظیمات بصورت کلی

کمی قبلتر در مقاله ای با نام رفتارها و تنظیمات پیشفرض ری اکت کوئری بطور کامل این تنظیمات و رفتارهای پیشفرض را توضیح دادیم اما با این حال اینجاهم یک نگاه دوباره ی بهشون می اندازیم.

 برای دستکاری تنظیمات پیشفرض و یا بطور کل اعمال یکسری تنظیمات بصورت عمومی باید بریم سراغ QueryClient :

import "@/styles/globals.css";
import { QueryClientProvider, QueryClient } from "@tanstack/react-query";

const client = new QueryClient({
 // کانفیگ های مدنظر
});

export default function App({ Component, pageProps }) {
  return (
    <QueryClientProvider client={client}>
      // کامپوننت اصلی app
    </QueryClientProvider>
  );
}

اعمال تنظیمات بصورت تکی

برای اعمال یکسری تنظیمات بصورت تکی و برای هربار استفادمون از هوک ها هم که میریم سراغ هوک مدنظر و تنظیمات مدنظر را به عنوان پارامترهای ورودی به هوک پاس میدیم:

const HomePage = () => {
  const {} = useQuery({
    // پارامترها و تنظیمات مدنظر
});

  return <p>Home</p>;
};

export default HomePage;

بریم سراغ رفتارها و تنظیمات پیشفرضی که روی ری اکت کوئری اعمال شدن و تک تک اونهارو باهم دیگه ببینیم.

staleTime

پارامتری به نام staleTime توی توی هوک هایی مثل useQuery و یا useInfiniteQuery در ری اکت کوئری وجود داره که مقدار پیشفرض برابر با 0 هستش. این عدد به ری اکت کوئری میگه تا چند دقیقه مجاز به استفاده از حافظه cache هست.

اگر این مقدار مساوی 0 باشه، ری اکت کوئری دیتای موجود در حافظه cache را کهنه در نظر میگیره و بهش اعتنایی نمیکنه و http request مارو میزنه و دیتای تازه رو از سرور دریافت میکنه. اما اگر این مقدار مساوی عددی غیر از صفر مثلا 10000 باشه که به معنای ده هزار میلی ثانیه یا به عبارتی ده ثانیه هستش، ری اکت کوئری تا ده ثانیه به همین دیتای توی cache اکتفا میکنه و صرفا دیتای موجود در حافظه cache را به کاربر نشون میده و دیگه http request به سمت سرور نمیزنه.

refetch در حالت های مختلف

یکسری زمان ها هست که ری اکت کوئری تصمیم میگیره بطور خودکار query های مارو مجددا fetch کنه ( منظور از refetch زدن یک ریکوئست مجدد به سمت سرور هستش ) که این حالت هارو میتونیم در زیر ببینیم:

• refetchOnWindowFocus: که درصورتی که کاربر بین تب ها یا مرورگر و یک برنامه دیگه جابجا بشه، به محض برگشتش به وبسایت ما، ری اکت کوئری بطور خودکار query هارو refetch میکنه. برای غیرفعال کردن این بخش باید refetchOnWindowFocus را مساوی false قرار بدیم.
• refetchOnReconnect: زمانیکه نت کاربر قطع بشه و بعد مجدد وصل بشه، به محض اتصال کاربر به اینترنت، ری اکت کوئری query هارو refetch میکنه.

مدت زمان نگه داری حافظه کش

ری اکت کوئری بطور پیشفرض دیتاهای کش شده را به مدت 5 دقیقه در حافظه کش نگه داری میکنه و درصورتی که تا مدت 5 دقیقه، هیچ query دیگه ایی با مشخصات کش ایجاد نشه، حافظه کش شده پاکسازی میشه. برای تغییر این زمان در نسخه 5 از react query باید یک مقداری را با واحد میلی ثانیه به پارامتر gcTime بدیم و در نسخه های قبل از 5 هم به پارامتر cacheTime

retry و retryDelay

react query بطور پیشفرض اگر یک query به ارور بخوره، میاد 3 بار اون query را با یک تاخیر کوتاهی refetch میکنه. یعنی چی ؟ یعنی اگر شما یکی از useQuery هاتون به ارور بخوره، ری اکت کوئری قبل از برگرداندن ارور، 3 بار دیگه اون useQuery را اجرا میکنه و اگر عینه 3 بار تکرار به ارور بخوره، اونوقت میاد و ارور رو به کاربر نشون میده.

برای تغییر این رفتار کافیه retry را مساوی false یا عدد دلخواه قرار بدیم.

اشتراک گذاری ساختاریه داده ها

ری اکت کوئری نتیجه query هارو بطور ساختاری به اشتراک میگذاره تا بتونه تشخیص بده چه زمانی واقعا دیتا تغییر میکنه. ری اکت کوئری برای این قسمت میگه که اگر بنظرتون عجیب میاد این موضوع، نیاز به هیچ نگرانی نیست چراکه این قسمت در 99.99% مواقع به بهترین شکل ممکن کار میکنه و تماما منفعته بدون ضرر هست برای اپلیکیشن شما.

اما اگر حس کردید که داره بد کار میکنه یا بخشی از برنامه شما بشدت سنگین و کند عمل میکنه، کافیه که structuralSharing  را مساوی false قرار بدید.

سخن نهایی

در این مقاله سعی کردیم تا شروعی سریع و تقریبا کامل را داشته باشیم و نصب و کانفیگ React Query را یاد بگیریم. در مقاله های آینده به سراغ تک تک بخش های ری اکت کوئری میریم و علاوه بر اینکه ری اکت کوئری را بطور کامل در دوره آموزشی ری اکت کوئری و آموزش فرانت اند یاد گرفتیم، در مقالات بعدی هم اونهارو یاد خواهیم گرفت.